Prepare everything for release 1.9.5

UserGuide.org

@@ -144,6 +144,7 @@ steps, using the freely available GNU FORTRAN compiler [[https://gcc.gnu.org/wik
 : git clone https://github.com/cdominik/optool.git        # clone repository
 : cd optool                      # enter code directory
 : make multi=true                # compile with multicore support
+: 
 : make install bindir=~/bin/     # optional: copy binaries to binary path
 : pip install -e .               # optional: install the python module
 
@@ -246,18 +247,19 @@ DHS with f_max=0.8.
 
 + =-a AMIN [AMAX [APOW [NA]]]= \hfill{}(powerlaw size distribution) ::
   Specify (minimum) grain radius, and optionally maximum grain radius,
-  the [[#internals][size distribution powerlaw]] and the number of size bins.  You may
+  the [[#sizedist][size distribution powerlaw]] and the number of size bins.  You may
   also use options to set individual values with *-amin*, *-amax*,
   *-apow*, *-na*. The defaults are 0.05 \mu{}m, 3000 \mu{}m, 3.5, and
   /10 per size decade with a fixed minimum of 5/, respectively.\\
   =>= If only a single size is specified with *-a*, then a_max=a_min and
   n_a=1 are implied.
 
 + =-a AMIN AMAX AMEAN:ASIG [NA]= \hfill{} ([log-]normal size distribution) ::
-  Specify centroid size and logarithmic width for a [[#internals][log-normal
+  Specify the centroid size and the logarithmic width for a [[#sizedist][log-normal
   size distribution]]. You may also use *-amean* and *-asig* options to
-  set these values. If =ASIG= is negative, its value is in \mu{}m and
-  it then triggers a [[#internals][normal distribution around =AMEAN=]].
+  set these values. If =ASIG= is negative, its value is interpreted to
+  denote the width (in \mu{}m) of a [[#sizedist][normal distribution]] around
+  =AMEAN=.
 
 ** Wavelength grid
 
@@ -273,10 +275,12 @@ DHS with f_max=0.8.
 
 + =-l FILE= ::
 
-  Read the wavelength grid from =FILE=.  The first non-comment line
-  needs to contain the number of wavelength values. In the data block
-  below it, the first column is expected to hold the wavelength
-  values, in \mu{}m. An [[#lnk-files][=lnk=]] file could be used here!
+  Read the wavelength grid from =FILE=. Lines in the file starting
+  with =*=, =!=, or =#= are treated as comment lines.  The first
+  non-comment line needs to start with the number of wavelength
+  values. In the data block below it, the first column is expected to
+  hold the wavelength values, in \mu{}m. An [[#lnk-files][=lnk=]] file could be used
+  here!
 
 ** Controlling the output
 
@@ -346,14 +350,14 @@ the few exceptions are highlighted by bold-face numbers.  If a
 material is being used outside of the measured region, =optool= will
 still function, using extrapolated optical properties.
 
-To get started with some kind of standard opacity, we recommend to
-work with pyroxene \fbox{pyr}, carbon \fbox{c}, and (at low
-temperaturs) water ice \fbox{h2o}.
+Even the limited number of materials we have selected to include with
+=optool= can be daunting. To get started with some kind of standard
+opacity, we recommend to work with pyroxene \fbox{pyr}, carbon
+\fbox{c}, and, at low temperatures, water ice \fbox{h2o} (Woitke+
+2016). If you need to account for sulfur, you may want to include
+troilite \fbox{tro} (Birnstiel+ 2016).
 
-#     #+LATEX: \newpage
-# #+begin_center
-# *Table 1:* Built-in materials
-# #+end_center
+#+LaTeX: \newpage\centerline{\textit{Table 1: Built-in materials}}
 #+ATTR_LATEX: :font \footnotesize\sf :align llllrrrlHH
 | *-c Key*   | *-c Key*    | *Material*              | *State* |      \rho | \lambda_min | \lambda_max | *Reference*   | *Comment*    | *File*                      |
 | generic    | full key    |                         |         |    g/cm^3 |      \mu{}m |      \mu{}m |               |              |                             |
@@ -382,7 +386,7 @@ temperaturs) water ice \fbox{h2o}.
 |            | c-nano      | C nano-diamond          | cryst   |       2.3 |        0.02 |       *110* | [[https://ui.adsabs.harvard.edu/abs/2004A%26A...423..983M][Mutschke+04]]   |              | [[file:lnk_data/c-nano-Mutschke2004.lnk][c-nano-Mutschke2004.lnk]]     |
 |------------+-------------+-------------------------+---------+-----------+-------------+-------------+---------------+--------------+-----------------------------|
 | iron       | fe-c        | Fe                      | metal   |      7.87 |         0.1 |         1e5 | [[https://ui.adsabs.harvard.edu/abs/1996A%26A...311..291H][Henning+96]]    |              | [[file:lnk_data/fe-c-Henning1996.lnk][fe-c-Henning1996.lnk]]        |
-|            | fes         | FeS                     | metal   |      4.83 |         0.1 |         1e5 | [[https://ui.adsabs.harvard.edu/abs/1996A%26A...311..291H][Henning+96]]    |              | [[file:lnk_data/fes-Henning1996.lnk][fes-Henning1996.lnk]]         |
+| \fbox{tro} | fes         | FeS                     | metal   |      4.83 |         0.1 |         1e5 | [[https://ui.adsabs.harvard.edu/abs/1996A%26A...311..291H][Henning+96]]    |              | [[file:lnk_data/fes-Henning1996.lnk][fes-Henning1996.lnk]]         |
 |            | sic         | SiC                     | cryst   |      3.22 |       0.001 |        1000 | [[https://ui.adsabs.harvard.edu/abs/1993ApJ...402..441L][Laor93]]        |              | [[file:lnk_data/sic-Draine1993.lnk][sic-Draine1993.lnk]]          |
 |------------+-------------+-------------------------+---------+-----------+-------------+-------------+---------------+--------------+-----------------------------|
 | qua        | sio2        | SiO_2                   | amorph  |      2.65 |      0.0006 |         500 | [[https://ui.adsabs.harvard.edu/abs/2007ApOpt..46.8118K][Kitamura+07]]   | \rho ?       | [[file:lnk_data/sio2-Kitamura2007.lnk][si02-Kitamura2007.lnk]]       |
@@ -399,7 +403,6 @@ temperaturs) water ice \fbox{h2o}.
 
 
 # | for      | ol-c-mg100  | Mg_{2}SiO_4            | cryst   |   3.33 |       *3.0* |         250 | [[https://ui.adsabs.harvard.edu/abs/1974PhDT.......274S][Steyer+74]]    | switch out?  | [[file:lnk_data/ol-c-mg100-Steyer1974.lnk][ol-c-mg100-Steyer1974.lnk]]   |
-
 # |          | icemix-c2d | H_{2}O/CO_{2}/CO mix    | ?       |    1.0 |        0.04 |         8e6 | [[https://ui.adsabs.harvard.edu/abs/2009ApJ...690..496C][Pontoppidan]]  | \rho?        | [[file:lnk_data/icemix-c2d-Pontoppidan2009.lnk][icemix-c2d-Pontoppidan2009.lnk]] |
 
 
@@ -419,12 +422,13 @@ following format:
   \lambda[\mu{}m] (sorted either up or down), and the real and
   imaginary parts of the refractive index, $n$ and $k$.
 
-More data ready for use with =optool= is in [[https://github.com/cdominik/optool-additional-refind-data][this repository]]. Other
-resources are the [[https://www.astro.uni-jena.de/Laboratory/Database/databases.html][Jena database]], [[http://eodg.atm.ox.ac.uk/ARIA/][ARIA]] and original papers in the
-literature. Don't forget to add the line with $n_\lambda$ and \rho!
-If that is not possible, =optool= will count the lines and you can
-specify the density after the mass fraction, like this: =optool -c
-path/to/file.lnk 0.7 3.42=.
+We provide additional data ready for use with =optool= is in [[https://github.com/cdominik/optool-additional-refind-data][this
+repository]]. Other resources are the [[https://www.astro.uni-jena.de/Laboratory/Database/databases.html][Jena database]], [[http://eodg.atm.ox.ac.uk/ARIA/][ARIA]] and original
+papers in the literature. Don't forget to add the line with
+$n_\lambda$ and \rho!  If that is not possible, =optool= will count
+the lines and you can specify the density after the mass fraction,
+like this: =optool -c path/to/file.lnk 0.7 3.42=.  Please do not forget
+to include references for any optical properties used in your study.
 
 #+LATEX: \newpage
 * Output files
@@ -567,6 +571,7 @@ $n_p=1$. The resulting object will have the following attributes:
 #+ATTR_LATEX: :width 14.8cm :options angle=0
 [[./maint/inspect.png]]
 
+#+LaTeX: \newpage
 Applying the =plot()= method to a =particle= object like =p.plot()=
 will produce these plots:
 - a plot showing the opacities \kappa_abs, \kappa_sca, and \kappa_ext
@@ -693,6 +698,10 @@ the right thing, converting to 1300\mu{}m, 881.7\mu{}m, and 2.5\mu{}m,
 respectively.
 
 * Size distribution
+:PROPERTIES:
+:CUSTOM_ID: sizedist
+:END:
+
 =optool= implements powerlaw, log-normal, and normal size
 distributions.  Each of these will be subject to a minimum and a
 maximum grain size. The grain size grid is logarithmic, so $da\propto
@@ -703,7 +712,7 @@ a$. The logarithmic bins are then filled according to:
 |                                     |                                                                                                  |
 Other size distributions can be constructed using the [[#python][python
 interface]].  A normal distribution is not sampled symmetrically on a
-logarithmic size grid - please make sure your samling is fine enough
+logarithmic size grid - please make sure your sampling is fine enough
 around the mean size.
 
 
@@ -804,7 +813,7 @@ simple as using the [[#builtin-materials][built-in materials]].  Here is how to
 4. Run =make ingest= to update =optool_refind.f90=, now with your new
    material.
 5. Recompile and install the code.
-
+#+LaTeX: \newpage
 * Overview of optical properties
 
 This grid plot shows the imaginary parts of all built-in materials, in
@@ -904,7 +913,7 @@ the code.
   sphere in the Rayleigh limit.
 
 [fn:7]still including the porosity specified with the *-p* switch
-(which is porosity residing in the monomers themspelves), but not any
+(which is porosity residing in the monomers themselves), but not any
 "porosity" resulting from the aggregate structure
 
 
@@ -937,6 +946,7 @@ We are indebted to
 #+LaTeX: \newpage
 * Bibliography
 #+LATEX: \footnotesize
+- Birnstiel, T. et al. 2016, ApJ 869, 45
 - Bohren, C.F. and Huffman, D.R. 1998, Wiley-VCH, \\
   /Absorption and Scattering of Light by Small Particles/
 - Draine, B. 2003, ApJ 598, 1017

optool_manual.f90

@@ -143,8 +143,10 @@ subroutine manual(what)
      write(*,'("  | optool pyr  -a 10 30  -mmf 0.3 1.9")')
      write(*,'("   ----")')
      write(*,'("")')
-     write(*,'("  Compute CDE for small graphite grains:  optool gra -a 0.01 0.1 -l 1 30")')
-     write(*,'("  -cde ")')
+     write(*,'("  Compute CDE for small graphite grains")')
+     write(*,'("  ,----")')
+     write(*,'("  | optool gra  -a 0.01 0.1 -l 1 30 -cde")')
+     write(*,'("   ----")')
      write(*,'("")')
      write(*,'("3 Installation")')
      write(*,'("==============")')
@@ -156,6 +158,7 @@ subroutine manual(what)
      write(*,'("  | git clone https://github.com/cdominik/optool.git        # clone repository")')
      write(*,'("  | cd optool                      # enter code directory")')
      write(*,'("  | make multi=true                # compile with multicore support")')
+     write(*,'("  | ")')
      write(*,'("  | make install bindir=~/bin/     # optional: copy binaries to binary path")')
      write(*,'("  | pip install -e .               # optional: install the python module")')
      write(*,'("   ----")')
@@ -292,11 +295,11 @@ subroutine manual(what)
   if((what.eq.'-a').or.(what.eq.'-amin').or.(what.eq.'-amax').or.(what.eq.'-apow').or.(what.eq.'-na').or.(what.eq.'all')&
           .or.(what.eq.'-amean').or.(what.eq.'-asig')) then
      write(*,'("   -a AMIN AMAX AMEAN:ASIG [NA]        ([log-]normal size distribution)")')
-     write(*,'("          Specify centroid size and logarithmic width for a [log-normal")')
-     write(*,'("        size distribution]. You may also use *-amean* and *-asig*")')
-     write(*,'("        options to set these values. If  ASIG  is negative, its value is")')
-     write(*,'("        in mum and it then triggers a [normal distribution around")')
-     write(*,'("         AMEAN ].")')
+     write(*,'("          Specify the centroid size and the logarithmic width for a")')
+     write(*,'("        [log-normal size distribution]. You may also use *-amean* and")')
+     write(*,'("        *-asig* options to set these values. If  ASIG  is negative, its")')
+     write(*,'("        value is interpreted to denote the width (in mum) of a [normal")')
+     write(*,'("        distribution] around  AMEAN .")')
      write(*,'("")')
   endif
   if(what.eq.'all') then
@@ -318,10 +321,12 @@ subroutine manual(what)
   endif
   if((what.eq.'-l').or.(what.eq.'-lmin').or.(what.eq.'-lmax').or.(what.eq.'-nl').or.(what.eq.'-nlam').or.(what.eq.'all')) then
      write(*,'("   -l FILE ")')
-     write(*,'("          Read the wavelength grid from  FILE .  The first non-comment")')
-     write(*,'("        line needs to contain the number of wavelength values. In the")')
-     write(*,'("        data block below it, the first column is expected to hold the")')
-     write(*,'("        wavelength values, in mum. An [ lnk ] file could be used here!")')
+     write(*,'("          Read the wavelength grid from  FILE . Lines in the file")')
+     write(*,'("        starting with  * ,  ! , or  #  are treated as comment lines.")')
+     write(*,'("        The first non-comment line needs to start with the number of")')
+     write(*,'("        wavelength values. In the data block below it, the first column")')
+     write(*,'("        is expected to hold the wavelength values, in mum. An [ lnk ]")')
+     write(*,'("        file could be used here!")')
      write(*,'("")')
   endif
   if(what.eq.'all') then
@@ -404,9 +409,12 @@ subroutine manual(what)
      write(*,'("  material is being used outside of the measured region,  optool  will")')
      write(*,'("  still function, using extrapolated optical properties.")')
      write(*,'("")')
-     write(*,'("  To get started with some kind of standard opacity, we recommend to")')
-     write(*,'("  work with pyroxene \fbox{pyr}, carbon \fbox{c}, and (at low")')
-     write(*,'("  temperaturs) water ice \fbox{h2o}.")')
+     write(*,'("  Even the limited number of materials we have selected to include with")')
+     write(*,'("   optool  can be daunting. To get started with some kind of standard")')
+     write(*,'("  opacity, we recommend to work with pyroxene \fbox{pyr}, carbon")')
+     write(*,'("  \fbox{c}, and, at low temperatures, water ice \fbox{h2o} (Woitke+")')
+     write(*,'("  2016). If you need to account for sulfur, you may want to include")')
+     write(*,'("  troilite \fbox{tro} (Birnstiel+ 2016).")')
      write(*,'("")')
      write(*,'("  -c Key      -c Key       Material                 State  Reference     ")')
      write(*,'(" generic     full key                                                    ")')
@@ -435,7 +443,7 @@ subroutine manual(what)
      write(*,'("             c-nano       C nano-diamond           cryst   Mutschke+04")')
      write(*,'("---------------------------------------------------------- --------------")')
      write(*,'(" iron        fe-c         Fe                       metal   Henning+96")')
-     write(*,'("             fes          FeS                      metal   Henning+96")')
+     write(*,'("      tro    fes          FeS                      metal   Henning+96")')
      write(*,'("             sic          SiC                      cryst   Laor93")')
      write(*,'("---------------------------------------------------------- --------------")')
      write(*,'(" qua         sio2         SiO_2                    amorph  Kitamura+07")')
@@ -464,12 +472,13 @@ subroutine manual(what)
      write(*,'("    (sorted either up or down), and the real and imaginary parts of the")')
      write(*,'("    refractive index, $n$ and $k$.")')
      write(*,'("")')
-     write(*,'("  More data ready for use with  optool  is in [this repository]. Other")')
-     write(*,'("  resources are the [Jena database], [ARIA] and original papers in the")')
-     write(*,'("  literature. Don t forget to add the line with $n_\lambda$ and rho!  If")')
-     write(*,'("  that is not possible,  optool  will count the lines and you can")')
-     write(*,'("  specify the density after the mass fraction, like this:  optool -c")')
-     write(*,'("  path/to/file.lnk 0.7 3.42 .")')
+     write(*,'("  We provide additional data ready for use with  optool  is in [this")')
+     write(*,'("  repository]. Other resources are the [Jena database], [ARIA] and")')
+     write(*,'("  original papers in the literature. Don t forget to add the line with")')
+     write(*,'("  $n_\lambda$ and rho!  If that is not possible,  optool  will count the")')
+     write(*,'("  lines and you can specify the density after the mass fraction, like")')
+     write(*,'("  this:  optool -c path/to/file.lnk 0.7 3.42 .  Please do not forget to")')
+     write(*,'("  include references for any optical properties used in your study.")')
      write(*,'("")')
      write(*,'("6 Output files")')
      write(*,'("==============")')
@@ -719,7 +728,7 @@ subroutine manual(what)
      write(*,'("   normal, triggered by sig<0         n(a) ~ exp[-0.5(\frac{a-a_m}{sig})^2]")')
      write(*,'("  Other size distributions can be constructed using the [python")')
      write(*,'("  interface].  A normal distribution is not sampled symmetrically on a")')
-     write(*,'("  logarithmic size grid - please make sure your samling is fine enough")')
+     write(*,'("  logarithmic size grid - please make sure your sampling is fine enough")')
      write(*,'("  around the mean size.")')
      write(*,'("")')
      write(*,'("10 Scattering Matrix: The fine print")')
@@ -948,6 +957,7 @@ subroutine manual(what)
      write(*,'("16 Bibliography")')
      write(*,'("===============")')
      write(*,'("")')
+     write(*,'("  - Birnstiel, T. et al. 2016, ApJ 869, 45")')
      write(*,'("  - Bohren, C.F. and Huffman, D.R. 1998, Wiley-VCH,")')
      write(*,'("    /Absorption and Scattering of Light by Small Particles/")')
      write(*,'("  - Draine, B. 2003, ApJ 598, 1017")')