[gnuastro-commits] master 3d810ae: Library (units & arithmetic): added distance (LY-PC-AU) conversions

[Mohammad Akhlaghi]

branch: master
commit 3d810ae4e35f0ece598095568ef80f7ee46498ee
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Library (units & arithmetic): added distance (LY-PC-AU) conversions
    
    Until now, there was no easy way to do conversions between standard
    distance measurements in astronomy. Users would have to have the conversion
    factors in mind (or search them in the internet!) to write a generic
    conversion in their script. But this was inconvenient!
    
    With this commit, six functions have been added to the Units ('units.h')
    library which are used by the Arithmetic library to define six new
    operators for all types of conversion between the three commonly used
    distance measures in astronomy: Light-years (LY), Parsecs (PC) and
    Astronomical Units (AU).
    
    While adding the items in the NEWS file, I noticed that I had forgot to
    thank Ignacio Trujillo for the new feature of CosmicCalculator, so that was
    also added.
    
    This task was implemented after a question raised by Markus Schaney.
---
 NEWS                         | 18 ++++++++-
 THANKS                       |  1 +
 doc/announce-acknowledge.txt |  1 +
 doc/gnuastro.texi            | 83 ++++++++++++++++++++++++++++++++++++++
 lib/arithmetic.c             | 36 +++++++++++++++++
 lib/gnuastro/arithmetic.h    |  6 +++
 lib/gnuastro/units.h         | 18 +++++++++
 lib/units.c                  | 95 ++++++++++++++++++++++++++++++++++++++++++++
 8 files changed, 256 insertions(+), 2 deletions(-)

diff --git a/NEWS b/NEWS
index fd50f29..2f1beea 100644
--- a/NEWS
+++ b/NEWS
@@ -24,15 +24,23 @@ See the end of the file for license conditions.
      to be more useful for a new user.
 
   Arithmetic:
-   - New operands (also available in Table's column arithmetic):
+   - New operands (also available in Table's column arithmetic, the
+     distance conversion operators were suggested by Markus Schaney):
      - box-around-ellipse: width and height of the box covering an ellipse.
+     - au-to-pc: Convert Astronomical Units (AUs) to Parsecs (PCs).
+     - pc-to-au: Convert Parsecs (PCs) to Astronomical Units (AUs).
+     - ly-to-pc: Convert Light-years (LYs) to Parsecs (PCs).
+     - pc-to-ly: Convert Parsecs (PCs) to Light-years (LYs).
+     - ly-to-au: Convert Light-years (LYs) to Astronomical Units (AUs).
+     - au-to-ly: Convert Astronomical Units (AUs) to Light-years (LYs).
 
   CosmicCalculator:
    - A warning is printed if the requested redshift is lower than 0.007
      (corresponding to ~30Mpc in Plank 2018 cosmology). Because at these
      scales the peculiar velocity of galaxies may be significant compared
      to the Hubble flow (which is the basis of the calculations here). The
-     warning can be suppressed with the '--quiet' option.
+     warning can be suppressed with the '--quiet' option. This was
+     suggested by Ignacio Trujillo.
 
   MakeCatalog:
    --areaerror: spatial resolution of image specified by user, used in
@@ -72,6 +80,12 @@ See the end of the file for license conditions.
      - GAL_ARITHMETIC_OP_BOX_AROUND_ELLIPSE
    - gal_wcs_write_wcsstr: wrapper of wcshdo of WCSLIB to simplify generic
      access to that low-level operation (has some extra sanity checks).
+   - gal_units_au_to_pc: Convert Astronomical Units to Parsecs.
+   - gal_units_pc_to_au: Convert Parsecs to Astronomical Units.
+   - gal_units_ly_to_pc: Convert Light-years to Parsecs.
+   - gal_units_pc_to_ly: Convert Parsecs to Light-years.
+   - gal_units_ly_to_au: Convert Light-years to Astronomical Units.
+   - gal_units_au_to_ly: Convert Astronomical Units to Light-years.
 
 ** Removed features
 
diff --git a/THANKS b/THANKS
index e8c9db5..6a0d777 100644
--- a/THANKS
+++ b/THANKS
@@ -89,6 +89,7 @@ support in Gnuastro. The list is ordered alphabetically (by 
family name).
     Teymoor Saifollahi                   teymur.saif@gmail.com
     Joanna Sakowska                      js01093@surrey.ac.uk
     Elham Saremi                         saremi@ipm.ir
+    Markus Schaney                       markus@riseup.net
     Yahya Sefidbakht                     y.sefidbakht@gmail.com
     Alejandro Serrano Borlaff            asborlaff@ucm.es
     Zahra Sharbaf                        samaeh.sharbaf2@yahoo.com
diff --git a/doc/announce-acknowledge.txt b/doc/announce-acknowledge.txt
index 2e37ab1..d168bbf 100644
--- a/doc/announce-acknowledge.txt
+++ b/doc/announce-acknowledge.txt
@@ -9,6 +9,7 @@ Raúl Infante-Sainz
 Matthias Kluge
 Juan Miro
 Juan Molina Tobar
+Markus Schaney
 Zahra Sharbaf
 Vincenzo Testa
 Ignacio Trujillo
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index c920d14..8e6e5a7 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -12932,6 +12932,56 @@ Therefore you can convert the units of SDSS image 
pixels to Janskys with the com
 $ astarithmetic sdss-image.fits 22.5 counts-to-jy
 @end example
 
+@item au-to-pc
+@cindex Parsecs
+@cindex Astronomical Units (AU)
+Convert Astronomical Units (AUs) to Parsecs (PCs).
+This operator takes a single argument which is interpretted to be the input 
AUs.
+The conversion is based on the definition of Parsecs: @mymath{1 \rm{PC} = 
1/tan(1^{\prime\prime}) \rm{AU}}, where @mymath{1^{\prime\prime}} is one 
arcseconds.
+In other words, @mymath{1 (\rm{PC}) = 648000/\pi (\rm{AU})}.
+For example, if we take Pluto's average distance to the Sun to be 40 AUs, we 
can obtain its distance in Parsecs using this command:
+
+@example
+echo 40 | asttable -c'arith $1 au-to-pc'
+@end example
+
+@item pc-to-au
+Convert Parsecs (PCs) to Astronomical Units (AUs).
+This operator takes a single argument which is interpretted to be the input 
PCs.
+For more on the conversion equation, see description of @code{au-to-pc}.
+For example, Proxima Centauri (the nearest star to the Solar system) is 1.3020 
Parsecs from the Sun, we can calculate this distance in units of AUs with the 
command below:
+
+@example
+echo 1.3020 | asttable -c'arith $1 pc-to-au'
+@end example
+
+@item ly-to-pc
+@cindex Light-year
+Convert Light-years (LY) to Parsecs (PCs).
+This operator takes a single argument which is interpretted to be the input 
LYs.
+The conversion is done from IAU's definition of the light-year 
(9460730472580800 m @mymath{\approx} 63241.077 AU = 0.306601 PC, for the 
conversion of AU to PC, see the description of @code{au-to-pc}).
+
+For example the distance of Andromeda galaxy to our galaxy is 2.5 million 
light-years, so its distance in kilo-Parsecs can be calculated with the command 
below (note that we want the output in kilo-parsecs, so we are dividing the 
output of this operator by 1000):
+
+@example
+echo 2.5e6 | asttable -c'arith $1 ly-to-pc 1000 /'
+@end example
+
+@item pc-to-ly
+Convert Parsecs (PCs) to Light-years (LY).
+This operator takes a single argument which is interpretted to be the input 
PCs.
+For the conversion and an example of the inverse of this operator, see the 
descrioption of @code{ly-to-pc}.
+
+@item ly-to-au
+Convert Light-years (LY) to Astronomical Units (AUs).
+This operator takes a single argument which is interpretted to be the input 
LYs.
+For the conversion and a similar example, see the descrioption of 
@code{ly-to-pc}.
+
+@item au-to-ly
+Convert Astronomical Units (AUs) to Light-years (LY).
+This operator takes a single argument which is interpretted to be the input 
AUs.
+For the conversion and a similar example, see the descrioption of 
@code{ly-to-pc}.
+
 @item minvalue
 Minimum value in the first popped operand, so ``@command{a.fits minvalue}'' 
will push the minimum pixel value in this image onto the stack.
 When this operator acts on a single image, the output (operand that is put 
back on the stack) will no longer be an image, but a number.
@@ -30223,6 +30273,39 @@ Convert counts to Janskys through an AB 
magnitude-based zero point.
 For more on the equation, see @ref{Brightness flux magnitude}.
 @end deftypefun
 
+@deftypefun double gal_units_au_to_pc (double @code{au})
+@cindex Parsecs
+@cindex Astronomical Units (AU)
+Convert the input value (assumed to be in Astronomical Units) to Parsecs.
+For the conversion equation, see the description of @code{au-to-pc} operator 
in @ref{Arithmetic operators}.
+@end deftypefun
+
+@deftypefun double gal_units_pc_to_au (double @code{pc})
+Convert the input value (assumed to be in Parsecs) to Astronomical Units (AUs).
+For the conversion equation, see the description of @code{au-to-pc} operator 
in @ref{Arithmetic operators}.
+@end deftypefun
+
+@deftypefun double gal_units_ly_to_pc (double @code{ly})
+@cindex Light-year
+Convert the input value (assumed to be in Light-years) to Parsecs.
+For the conversion equation, see the description of @code{ly-to-pc} operator 
in @ref{Arithmetic operators}.
+@end deftypefun
+
+@deftypefun double gal_units_pc_to_ly (double @code{pc})
+Convert the input value (assumed to be in Parsecs) to Light-years.
+For the conversion equation, see the description of @code{ly-to-pc} operator 
in @ref{Arithmetic operators}.
+@end deftypefun
+
+@deftypefun double gal_units_ly_to_au (double @code{ly})
+Convert the input value (assumed to be in Light-years) to Astronomical Units.
+For the conversion equation, see the description of @code{ly-to-pc} operator 
in @ref{Arithmetic operators}.
+@end deftypefun
+
+@deftypefun double gal_units_au_to_ly (double @code{au})
+Convert the input value (assumed to be in Astronomical Units) to Light-years.
+For the conversion equation, see the description of @code{ly-to-pc} operator 
in @ref{Arithmetic operators}.
+@end deftypefun
+
 @node Spectral lines library, Cosmology library, Unit conversion library, 
Gnuastro library
 @subsection Spectral lines library (@file{speclines.h})
 
diff --git a/lib/arithmetic.c b/lib/arithmetic.c
index bce3c2f..ec646c4 100644
--- a/lib/arithmetic.c
+++ b/lib/arithmetic.c
@@ -573,6 +573,18 @@ arithmetic_function_unary(int operator, int flags, 
gal_data_t *in)
       UNIARY_FUNCTION_ON_ELEMENT( acosh, +0, +0);         break;
     case GAL_ARITHMETIC_OP_ATANH:
       UNIARY_FUNCTION_ON_ELEMENT( atanh, +0, +0);         break;
+    case GAL_ARITHMETIC_OP_AU_TO_PC:
+      UNIARY_FUNCTION_ON_ELEMENT( gal_units_au_to_pc, +0, +0); break;
+    case GAL_ARITHMETIC_OP_PC_TO_AU:
+      UNIARY_FUNCTION_ON_ELEMENT( gal_units_pc_to_au, +0, +0); break;
+    case GAL_ARITHMETIC_OP_LY_TO_PC:
+      UNIARY_FUNCTION_ON_ELEMENT( gal_units_ly_to_pc, +0, +0); break;
+    case GAL_ARITHMETIC_OP_PC_TO_LY:
+      UNIARY_FUNCTION_ON_ELEMENT( gal_units_pc_to_ly, +0, +0); break;
+    case GAL_ARITHMETIC_OP_LY_TO_AU:
+      UNIARY_FUNCTION_ON_ELEMENT( gal_units_ly_to_au, +0, +0); break;
+    case GAL_ARITHMETIC_OP_AU_TO_LY:
+      UNIARY_FUNCTION_ON_ELEMENT( gal_units_au_to_ly, +0, +0); break;
     case GAL_ARITHMETIC_OP_RA_TO_DEGREE:
       UNIFUNC_RUN_FUNCTION_ON_ELEMENT_STRING(double, gal_units_ra_to_degree);
       break;
@@ -2173,6 +2185,18 @@ gal_arithmetic_set_operator(char *string, size_t 
*num_operands)
     { op=GAL_ARITHMETIC_OP_MAG_TO_COUNTS;     *num_operands=2;  }
   else if (!strcmp(string, "counts-to-jy"))
     { op=GAL_ARITHMETIC_OP_COUNTS_TO_JY;      *num_operands=2;  }
+  else if( !strcmp(string, "au-to-pc"))
+    { op=GAL_ARITHMETIC_OP_AU_TO_PC;          *num_operands=1;  }
+  else if( !strcmp(string, "pc-to-au"))
+    { op=GAL_ARITHMETIC_OP_PC_TO_AU;          *num_operands=1;  }
+  else if( !strcmp(string, "ly-to-pc"))
+    { op=GAL_ARITHMETIC_OP_LY_TO_PC;          *num_operands=1;  }
+  else if( !strcmp(string, "pc-to-ly"))
+    { op=GAL_ARITHMETIC_OP_PC_TO_LY;          *num_operands=1;  }
+  else if( !strcmp(string, "ly-to-au"))
+    { op=GAL_ARITHMETIC_OP_LY_TO_AU;          *num_operands=1;  }
+  else if( !strcmp(string, "au-to-ly"))
+    { op=GAL_ARITHMETIC_OP_AU_TO_LY;          *num_operands=1;  }
 
   /* Statistical/higher-level operators. */
   else if (!strcmp(string, "minvalue"))
@@ -2361,6 +2385,12 @@ gal_arithmetic_operator_string(int operator)
     case GAL_ARITHMETIC_OP_COUNTS_TO_MAG:   return "counts-to-mag";
     case GAL_ARITHMETIC_OP_MAG_TO_COUNTS:   return "mag-to-counts";
     case GAL_ARITHMETIC_OP_COUNTS_TO_JY:    return "counts-to-jy";
+    case GAL_ARITHMETIC_OP_AU_TO_PC:        return "au-to-pc";
+    case GAL_ARITHMETIC_OP_PC_TO_AU:        return "pc-to-au";
+    case GAL_ARITHMETIC_OP_LY_TO_PC:        return "ly-to-pc";
+    case GAL_ARITHMETIC_OP_PC_TO_LY:        return "pc-to-ly";
+    case GAL_ARITHMETIC_OP_LY_TO_AU:        return "ly-to-au";
+    case GAL_ARITHMETIC_OP_AU_TO_LY:        return "au-to-ly";
 
     case GAL_ARITHMETIC_OP_MINVAL:          return "minvalue";
     case GAL_ARITHMETIC_OP_MAXVAL:          return "maxvalue";
@@ -2478,6 +2508,12 @@ gal_arithmetic(int operator, size_t numthreads, int 
flags, ...)
     case GAL_ARITHMETIC_OP_ASINH:
     case GAL_ARITHMETIC_OP_ACOSH:
     case GAL_ARITHMETIC_OP_ATANH:
+    case GAL_ARITHMETIC_OP_AU_TO_PC:
+    case GAL_ARITHMETIC_OP_PC_TO_AU:
+    case GAL_ARITHMETIC_OP_LY_TO_PC:
+    case GAL_ARITHMETIC_OP_PC_TO_LY:
+    case GAL_ARITHMETIC_OP_LY_TO_AU:
+    case GAL_ARITHMETIC_OP_AU_TO_LY:
     case GAL_ARITHMETIC_OP_RA_TO_DEGREE:
     case GAL_ARITHMETIC_OP_DEC_TO_DEGREE:
     case GAL_ARITHMETIC_OP_DEGREE_TO_RA:
diff --git a/lib/gnuastro/arithmetic.h b/lib/gnuastro/arithmetic.h
index 9f4c654..afdcb90 100644
--- a/lib/gnuastro/arithmetic.h
+++ b/lib/gnuastro/arithmetic.h
@@ -129,6 +129,12 @@ enum gal_arithmetic_operators
   GAL_ARITHMETIC_OP_COUNTS_TO_MAG,/* Counts to magnitude. */
   GAL_ARITHMETIC_OP_MAG_TO_COUNTS,/* Magnitude to counts. */
   GAL_ARITHMETIC_OP_COUNTS_TO_JY, /* Counts to Janskys with AB-mag zeropoint. 
*/
+  GAL_ARITHMETIC_OP_AU_TO_PC,     /* Astronomical units (AU) to Parsecs (PC). 
*/
+  GAL_ARITHMETIC_OP_PC_TO_AU,     /* Parsecs (PC) to Astronomical units (AU). 
*/
+  GAL_ARITHMETIC_OP_LY_TO_PC,     /* Astronomical units (AU) to Parsecs (PC). 
*/
+  GAL_ARITHMETIC_OP_PC_TO_LY,     /* Parsecs (PC) to Astronomical units (AU). 
*/
+  GAL_ARITHMETIC_OP_LY_TO_AU,     /* Light-years to Astronomical units (AU). */
+  GAL_ARITHMETIC_OP_AU_TO_LY,     /* Astronomical units (AU) to Light-years. */
 
   GAL_ARITHMETIC_OP_MINVAL,       /* Minimum value of array.               */
   GAL_ARITHMETIC_OP_MAXVAL,       /* Maximum value of array.               */
diff --git a/lib/gnuastro/units.h b/lib/gnuastro/units.h
index 229c610..71d86a1 100644
--- a/lib/gnuastro/units.h
+++ b/lib/gnuastro/units.h
@@ -82,6 +82,24 @@ gal_units_mag_to_counts(double mag, double zeropoint);
 double
 gal_units_counts_to_jy(double counts, double zeropoint_ab);
 
+double
+gal_units_au_to_pc(double au);
+
+double
+gal_units_pc_to_au(double pc);
+
+double
+gal_units_ly_to_pc(double ly);
+
+double
+gal_units_pc_to_ly(double pc);
+
+double
+gal_units_ly_to_au(double ly);
+
+double
+gal_units_au_to_ly(double au);
+
 __END_C_DECLS    /* From C++ preparations */
 
 #endif           /* __GAL_UNITS_H__ */
diff --git a/lib/units.c b/lib/units.c
index d93dcbf..6a311e5 100644
--- a/lib/units.c
+++ b/lib/units.c
@@ -386,3 +386,98 @@ gal_units_counts_to_jy(double counts, double zeropoint_ab)
 {
   return counts * 3631 * pow(10, -1 * zeropoint_ab / 2.5);
 }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+/**********************************************************************/
+/****************         Distance conversions        *****************/
+/**********************************************************************/
+/* Convert Astronomical Units (AU) to Parsecs (PC). From the definition
+   of Parsecs, 648000/pi AU = 1 PC. So   */
+double
+gal_units_au_to_pc(double au)
+{
+  return au / 648000.0f * 3.14159265358979323846264338327f;
+}
+
+
+
+
+
+/* Convert Parsecs (PC) to Astronomical units (AU), see comment of
+   'gal_units_au_to_pc'. */
+double
+gal_units_pc_to_au(double au)
+{
+  return au * 648000.0f / 3.14159265358979323846264338327f;
+}
+
+
+
+
+
+/* Convert Light-years to Parsecs, according to
+   https://en.wikipedia.org/wiki/Light-year#Definitions:
+
+   1 light-year = 9460730472580800 metres (exactly)
+                ~ 9.461 petametres
+                ~ 9.461 trillion kilometres (5.879 trillion miles)
+                ~ 63241.077 astronomical units
+                ~ 0.306601 parsecs  */
+double
+gal_units_ly_to_pc(double ly)
+{
+  return ly * 0.306601f;
+}
+
+
+
+
+
+/* Convert Parsecs to Light-years (see comment of gal_units_ly_to_pc). */
+double
+gal_units_pc_to_ly(double pc)
+{
+  return pc / 0.306601f;
+}
+
+
+
+
+
+/* Convert Astronomical Units to Light-years (see comment of
+   gal_units_ly_to_pc). */
+double
+gal_units_au_to_ly(double au)
+{
+  return au / 63241.077f;
+}
+
+
+
+
+
+/* Convert Light-years to Astronomical Units (see comment of
+   gal_units_ly_to_pc). */
+double
+gal_units_ly_to_au(double ly)
+{
+  return ly * 63241.077f;
+}