[gnuastro-commits] master 0545e7ea: Clarify that arcsectandist is in physical kpc; other copyedits

[Mohammad Akhlaghi]

branch: master
commit 0545e7ea6b993361f37a2e970c1f411565605f54
Author: Boud Roukema <boud@cosmo.torun.pl>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Clarify that arcsectandist is in physical kpc; other copyedits
    
    Until now, the '--help' output and Info documentation for the
    '--arcsectandist' option did not state whether the tangential distance was
    calculated in comoving or physical distance units.
    
    While it is natural to expect physical units for such a small angle,
    someone might guess that multiplying by 3600 gives the tangential distance
    for an arc subtending one degree. However, at one degree, the comoving
    separation for redshifts from 1 to 10 is about 100 Mpc give or take 50% or
    so, i.e. this is the cosmic web scale, where comoving units usually make
    more sense than physical units.
    
    With this commit, to avoid people not being sure what the intended unit is,
    the word "physical" is added in the description to clarify that these are
    the units of "ordinary" physics as opposed to comoving FLRW distance units.
    
    Some other copyediting is also done in this commit, including a comment for
    the proper distance that it is in comoving units (by definition). For
    distances such as the angular diameter distance or the luminosity distance,
    it would be meaningless to describe the units as either physical or
    comoving, since these do not represent point-A-to-point-B distances in the
    sense of the FLRW model.
    
    Disclaimer: I have not checked the volume calculation.
---
 bin/cosmiccal/args.h |  2 +-
 doc/gnuastro.texi    | 23 ++++++++++++++---------
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/bin/cosmiccal/args.h b/bin/cosmiccal/args.h
index b032c0ab..0bc80e55 100644
--- a/bin/cosmiccal/args.h
+++ b/bin/cosmiccal/args.h
@@ -209,7 +209,7 @@ struct argp_option program_options[] =
       UI_KEY_ARCSECTANDIST,
       0,
       0,
-      "Tangential dist. covered by 1arcsec at z (kpc).",
+      "Tangential dist. for 1arcsec at z (physical kpc).",
       UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 8c95ad9e..6bbe93bd 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -2546,7 +2546,7 @@ $ astcosmiccal -z2
 ## something without modifying the command you want to run.
 $ astcosmiccal -z2 --help
 
-## Only print the "Tangential dist. covered by 1arcsec at z (kpc)".
+## Only print the "Tangential dist. for 1arcsec at z (physical kpc)".
 ## in units of kpc/arc-seconds.
 $ astcosmiccal -z2 --arcsectandist
 
@@ -33113,21 +33113,26 @@ The current age of the universe (given the input 
parameters) in Ga (Giga annum,
 
 @item -C
 @itemx --criticaldensitynow
-The current critical density (given the input parameters) in grams per 
centimeter-cube (@mymath{g/cm^3}).
+The current critical density (given the input parameters) in grams per cubic 
centimeter (@mymath{g/cm^3}).
 
 @item -d
 @itemx --properdistance
-The proper distance (at current time) to object at the given redshift in 
Megaparsecs (Mpc).
+The proper distance (at the current time, i.e. in comoving units) to an object 
at the given redshift in Megaparsecs (Mpc).
 See @ref{Distance on a 2D curved space} for a description of the proper 
distance.
 
 @item -A
 @itemx --angulardiamdist
-The angular diameter distance to object at given redshift in Megaparsecs (Mpc).
+The angular diameter distance to an object at a given redshift in Megaparsecs 
(Mpc).
 
 @item -s
 @itemx --arcsectandist
-The tangential distance covered by 1 arc-seconds at the given redshift in 
kiloparsecs (Kpc).
-This can be useful when trying to estimate the resolution or pixel scale of an 
instrument (usually in units of arc-seconds) at a given redshift.
+The tangential distance covered by 1 arc-second at a given redshift in 
physical (not comoving) kiloparsecs (kpc).
+This can be useful when trying to estimate the resolution or pixel scale of an 
instrument (usually in units of arc-seconds) required for a galaxy of a given 
physical size at a given redshift.
+
+Note that since this is not in comoving units, multiplying the result by 3600 
will not give the tangential distance for an arc subtending one degree at 
higher redshifts.
+This is because, at one degree, the comoving separation for redshifts from 1 
to 10 is about 100 Mpc give or take 50% or so.
+In other words, this is the cosmic web scale, where comoving units usually 
make more sense than physical units.
+But this option is rarely used for such large arcs at higher redshifts, so for 
smaller arcs and lower redshifts, it will be sufficiently accurate.
 
 @item -L
 @itemx --luminositydist
@@ -33149,8 +33154,8 @@ Age of the universe at given redshift in Ga (Giga 
annum, or billion years).
 
 @item -b
 @itemx --lookbacktime
-The look-back time to given redshift in Ga (Giga annum, or billion years).
-The look-back time at a given redshift is defined as the current age of the 
universe (@option{--agenow}) subtracted by the age of the universe at the given 
redshift.
+The look-back time to a given redshift in Ga (Giga annum, or billion years).
+The look-back time at a given redshift is defined as the current age of the 
universe (@option{--agenow}) minus the age of the universe at the given 
redshift.
 
 @item -c
 @itemx --criticaldensity
@@ -33158,7 +33163,7 @@ The critical density at given redshift in grams per 
centimeter-cube (@mymath{g/c
 
 @item -v
 @itemx --onlyvolume
-The comoving volume in Megaparsecs cube (Mpc@mymath{^3}) until the desired 
redshift based on the input parameters.
+The comoving volume in cubic Megaparsecs (Mpc@mymath{^3}) through to the 
desired redshift, based on the input parameters.
 
 @end table