# optool

**Repository Path**: wcp_code/optool

## Basic Information

- **Project Name**: optool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-01-17
- **Last Updated**: 2024-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


* Introduction to optool

This tool produces complex dust particle opacities right from the
command line. It is derived from Michiel Min's DHS [[https://dianaproject.wp.st-andrews.ac.uk/data-results-downloads/fortran-package/][OpacityTool]] and
also implements Ryo Tazaki's MMF theory for highly porous aggregates.

* Capabilities

- stand-alone tool, fully command line driven, no input files need to
  be edited
- full scattering matrix output in several formats, including for
  RADMC-3D
- combining materials through mixing into a complex grain with
  porosity
- /built-in/: a curated collection of materials for applications in
  astronomy
- external refractive index data can be used just as easily
- computational methods: (i) *DHS (Distribution of Hollow Spheres)*
  for /irregular grains/ and /low-porosity/ aggregates.  Standard *Mie
  theory* for /perfect spheres/ is available as a limiting case. (ii)
  *MMF (Modified Mean Field)* theory for /high-porosity/fractal
  aggregates/.  (iii) *CDE* approximation in the Rayleigh limit.
- =Python= interface module for plotting and post-processing

* Terms of use

=optool= is distributed under the [[https://opensource.org/licenses/MIT][MIT license]] and can be used, changed
and redistributed freely. But we do ask you to provide a reference to
=optool= when using it.  Relevant references are listed below and the
corresponding BibTeX entries are available in the file
=optool.bib=. =optool= is [[https://github.com/cdominik/optool.git][hosted on github]].

- *optool:* [[https://ui.adsabs.harvard.edu/abs/2021ascl.soft04010D][Dominik, C., Min, M. & Tazaki, R. 2021, Optool, 1.9,
  Astrophysics Source Code Library, ascl:2104.010]]
- *DHS model for irregular grains:*  [[https://ui.adsabs.harvard.edu/abs/2005A%26A...432..909M][Min, M. et al. 2005, A&A, 432, 909]]
- *MMF model for aggregates:* [[https://ui.adsabs.harvard.edu/abs/2018ApJ...860...79T][Tazaki, R. & Tanaka,H. 2018, ApJ 860, 79]]
- *DIANA standard Opacities:* [[https://ui.adsabs.harvard.edu/abs/2016A%26A...586A.103W][Woitke, P. et al. 2016, A&A 586, 103]]
- *Third party software:* [[https://ui.adsabs.harvard.edu/abs/1981ApOpt..20.3657T][Toon, O. et al. 1981, Applied Optics 20, 3657]]
- References to refractive index data used in your particular
  application.

* Examples
A simple grain made only of the default pyroxene, for the default
grain size distribution (a^{-3.5} powerlaw from 0.05 to 3000\mu{}m),
on the default wavelength grid (0.05\mu{}m to 1cm).

: optool pyr

Include the scattering matrix in the produced output

: optool pyr -s

Reproduce the DIANA standard dust model, using a specific pyroxene
(70% Mg) and carbon, in a mass ratio 0.87/0.13, and with a porosity of
25%.

: optool pyr-mg70 0.87  c 0.13  -p 0.25

List the built-in materials

: optool -c

Add a water ice mantle (built-in data from Warren+08) that is 20% of
the core mass

: optool pyr-mg70 0.87  c 0.13  -m h2o-w 0.2  -p 0.25

Like the previous example, but use ice refractive index data from a
separate file.

: optool pyr-mg70 0.87  c 0.13  -p 0.25  -m data/ice_hudgins.dat 0.2

Pure water ice grains in a narrow size distribution from 1 to 3
microns, with 15 sample sizes following an f(a)\propto a^{-2.5}
powerlaw size distribution. Also, restrict the wavelength range to
10-100\mu{}m, and turn off DHS to get perfect spheres.

: optool h2o  -a 1 3 2.5 15  -l 10 100 -fmax 0

For silicon carbide, compute the opacity of a single grains size (2.5\mu{}m)
at \lambda=8.9\mu{}m.

: optool -a 2.5 -l 8.9 sic

Represent the default dust model (DIANA, you also get this when you do
not give any materials at all) in 42 grain sizes, and produce input
files for RADMC-3D, one for each grain size, with full scattering
matrix, chopping 3 degrees from the scattering peak.

: optool -na 42 -d -s -radmc -chop 3

Use MMF to compute the opacities of dust aggregates made of pyroxene
monomers.  Use a monomer radius of 0.3 \mu{}m to construct aggregates
with compact-volume radii between 10 and 30 \mu{}m, and a fractal
dimension of 1.9.

: optool pyr  -a 10 30  -mmf 0.3 1.9

Compute the CDE approximation of small graphite grains.

: optool gra  -a 0.01 0.1 -l 1 30 -cde


* Acknowledgments
- The [[https://www.astro.uni-jena.de/Laboratory/Database/databases.html][Jena Database of Optical Constants]] and the [[http://eodg.atm.ox.ac.uk/ARIA/][Aerosol Refractive
  Index Archive]] for their invaluable collections of refractive index
  datasets.
- Rens Waters, Thomas Henning, Xander Tielens, Elisabetta Palumbo,
  Laurent Pilon, Jeroen Bouwman, and Melissa McClure for discussions
  around optical properties of cosmic dust analogues.
- Charlène Lefèvre for [[https://github.com/charlenelefevre/SIGMA][SIGMA]], which inspired me to add grain mantles.
- Kees Dullemond for discussions about the [[https://www.ita.uni-heidelberg.de/~dullemond/software/radmc-3d/][RADMC-3D]] input format and
  the scattering matrix, for the idea to write =optool2tex= and for
  letting me include his incredible python plotting routine =viewarr=
  ([[https://github.com/dullemond/interactive_plot][available on github]]).
- Gabriel-Dominique Marleau for testing and feedback, in particular on
  =optool2tex=.
* User Guide
See the [[file:UserGuide.pdf][User Guide]] for more information.
* Important changes


- Release 1.9.4 ::
  - Improve installation process and instructions.
  - Get help about specific command line options with, for example,
    =optool -h mmf=.
  - Shell completion of command line options and arguments is now
    supported with the =optool-complete= script.  You need to link it
    into your shell setup using the instructions in =optool-complete=.

- Release 1.9.3 ::
  - New option -print, to direct output to STDOUT instead of files.
  - Grain sizes and wavelengths can be specified on the command lines
    in units other than microns, for example mm or GHz (frequency) or
    cm^-1 (wavenumbers).
  - Add Fayalite and also the Mg-rich Olivine from Fabian 2001.
  - Switch out the Forsterite dataset: Steyer is out, Suto is in.
  - Continuous Distribution of Ellipsoids (CDE) approximation has been
    implemented.  It is only valid in the Rayleigh limit and includes
    quite extreme particle shapes, but it is good as a comparison and
    frequently used in the literature.
  - "optool -a 15 -2" will compute a size range from 13-17um with a
    flat size distribution.
  
- Release 1.9 ::
  - The proper reference for optool is now the entry in the
    [[https://ascl.net][Astrophysics Source Code Library]], please refer to it when optool
    is used in your paper.  The reference looks like this:
    - Dominik, C., Min, M., Tazaki, R. 2021, Optool, 1.9, Astrophysics
      Source Code Library, record ascl:2104.010 
    Here is a [[https://ui.adsabs.harvard.edu/abs/2021ascl.soft04010D][pointer to the ADS entry]], from where you can also
    download the corresponding BibTeX entry.  That BibTeX entry is
    also in =optool.bib=, with the citation key =2021ascl.soft04010D=.
  - Add an amophous water ice, from Hudgins 1993.
    This dataset is amended at short and long wavelengths with the
    Warren data of crystalline ice, to get a wide dataset.

- Release 1.8.3 ::
  - Implement optool2tex, a little tool that turns an optool command
    line into a LaTeX snippet that describes the methods and the
    refractive index data used for that computation.  This is somewhat
    of a gimmick, but it is fun.
  - New way to keep precomputed opacities in a directory and read them
    back in in python at a later time.
  - New =sizedist()= method for quickly applying size distributions to
    a set of precomputed opacities.
  - The command line that was used to produce an output file is now
    stored in the file header of each output file - very handy if you
    are trying to reproduce a run.

- Release 1.7.3 ::
  - New built-in materials: SiO2
  - Stabilization of the interpolation and extrapolation of refractive
    index data.  Zero values did cause problems with the loglog
    scheme.  This is now fixed by using a floor of 1e-10 for both n
    and k values.
  - New =select()= method for the =optool.particle class=, to pull a
    particle size out of an object with many particle sizes in it
    (because it was computed by =optool= with the -d switch).
  - Implementation of particle arithmetic in the python module, to
    allow constructing grain models by adding separate grain types.

- Release 1.7 ::
  - New built-in materials (ices!): CO, CO2, CH3OH, CH4, and NH3.
  - Mean opacities can be computed in the Python module.
  - the =scatnorm= method in the Python module allows to renormalize
    the scattering matrix to various conventions used in the
    literature.
  - The python module contains a class for =lnk= files, that can be used
    to read tables, convert units, sort, smooth and decimate the
    data.  This is not described in the UserGuide, but after loading
    =optool.py=, the documentation will be available in python.
- Release 1.5 ::
  - An implementation of the Modified Mean Field Theory (MMF, Tazaki &
    Tanaka 2018) to treat opacities of very porous or fractal
    aggregates has been added.