https://github.com/sevenian3/ChromaStarPy
Tip revision: 103d3d0df6d9574c49818f149e1cae8100455d10 authored by Ian Short on 06 July 2023, 18:09:20 UTC
Create ReadMe
Create ReadMe
Tip revision: 103d3d0
README.txt
ChromaStarPy README: Getting Started quickly:
Updated July 2019
December 2017
Ian Short
Saint Mary's University
Halifax, NS, Canada
** History and references
This is the python V. 3 port of the Java atmospheric modeling and spectrum synthesis
code ChromaStarServer, formerly known as GrayStarServer,
supplemented with the two-level-atom facility of ChromaStar (formerly GrayStar).
July 2019 - Equation of state (EOS) and chemical/ionization equilibrium now computed
with Phil Bennett's "GAS" package. Includes 51 molecules, including 16 polyatomic
molecules
The version numbering is date-based using the ISO 8601 scheme YYYY-MM-DD
References:
Bennett, P.D., "A fast, robust algorithm for the solution of the equation of state for
late-type stellar atmospheres", 1983, M.Sc. Thesis, University of British Columbia" ("GAS")
Short, C. Ian, 2017, ChromaStarDB: SQL Database-driven Spectrum Synthesis and More,
PASP, 129, 094504, 11 pp., arXiv:1707.07725
Short, C. Ian, 2016, GrayStarServer: Server-side Spectrum Synthesis with a Browser-based
Client-side User Interface, PASP, 128, 104503, 11 pp., arXiv:1605.09368
** License
* The MIT License (MIT)
* Copyright (c) 2016 C. Ian Short
*
* Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:
*
* The above copyright notice and this permission notice shall
be included in all copies or substantial portions of the
Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
** Fundamental assumptions
Atmospheric structure: Un-blanketed, LTE, static, 1D, plane-parallel geometry
Chemical equilibrium: See Phil Bennett's GAS package
Spectrum synthesis: Power law approximation for the Voigt line profile, opacity due to lines whose line-center
wavelengths fall in the synthesis region only (eg. if you synthesize from 390 to 395 nm for the Sun, you will get
the Ca II K line opacity, but NOT the effect of the Ca II H blue line wing - synthesize from 390 - 400 nm to get both
everywhere in the range.)
**
** Installation and initial set-up:
**
Unzip the source tarball: gunzip ChromaStarPy.tar.gz
To extract the ChromaStarPy directory structure, and all needed source files and inputs data files:
tar xvf ChromaStarPy.tar
This will create a subdirectory in the current directory called ChromaStarPy/ with subdirectories called
InputData/, Inputs/, Outputs/, linpack/ and blas/
- All source files (*.py) are in ChromaStarPy/, linpack/, and blas/
- The ascii and byte-data versions of the atomic line list are in InputData/ in files with a .dat file
extension. The byte-data version contains the string "Bytes" at the end of its main filename
- Sample input files for setting up an atmosphere and spectrum modeling run are in the Input/ directory.
- By default the code writes all results to files in the Outputs/ directory
Setting the environment:
ChromaStarPy must import the matlplotlib [1] and numpy [2] python modules. It is recommended that the user
obtain a comprehensive python installation that will likely ship with these, such as the python distribution
available through the Anaconda package manager (anaconda.org/anaconda/python).
ChromaStar will automatically detect the OS, and will automatically determine the current directory (the
'run directory') for the cases where the OS is Windows or Unix/Linux, and will set the value of its absPath
variable. ChromaStaryPy will most likely work as is if the run directory is the installation directory.
Atomic line list:
ChromaStar expects to read the byte-data version of the line list in a subdirectory of the installation/run
directory called InputData/*.dat. A default line list ships with the tarball.
[1] Hunter, J. D., Matplotlib: A 2D graphics environment, 2007, Computing In Science & Engineering, 9, 90
[2] van der Walt, S., Colbert, S.C. & and Varoquaux, G., The NumPy Array: A Structure for Efficient Numerical
Computation, 2011, Computing in Science & Engineering, 13, 22
**
** Running
**
ChromaStarPy is known to run as of Python V. 3.6 in the spYder V. 3.2.3 IDE under Windows 10, and as of python
V. 2.7 under linux (see the note about required python modules in "Installation and initial set-up"). The main
program resides in source file ChromaStarGasPy.py and all other source files are 'import'ed here - the user must
"run" this file in the IDE to run the code.
To run at the command line prompt outside an IDE:
python ./ChromaStarGasPy.py
To run in an IDE:
Open ChromaStarGasPy.py
Click 'Run'
Textual run-time indicators at the console prompt, in order of appearance:
Echoes the OS it has detected and echoes the absolute path of the run directory it has detected (value of
its absPath variable) in which it expects to find the InputData/ and Outputs/ directories (see "Installation
and initial set-up").
Echoes which plot the user has selected (see "Setting up a modeling run" and "Outputs").
Confirms that it has parsed the input file by echoing back the names and values of all input parameters.
Indicates whether it is running the routines suitable for "Hot stars" or "Cool stars" (the "mode"),
and the estimated spectral type based on the stellar data in Appendix G of An Introduction to Modern
Astrophysics, 2nd Ed. by Bradley W. Carroll and Dale A. Ostlie.
Indicates when it is beginning to read the atomic line list (meaning the atmospheric structure has
been calculated), and when it has finished doing so.
Indicates when it has begun the spectrum synthesis stage of the calculation, and then when it has
finished doing so.
Echoes the value of Teff that it has recovered from an extended rectangle-rule numerical
integration of the modeled monochromatic flux spectrum between 260 and 2600 nm, and the computed
values of seven Johnson UBVRIJHK color indices for the model.
**
** Setting up a modeling run
**
ChromaStarPy is most likely to work if the run directory is the same as the main installation directory
(ChromaStarPy/), in keeping with the default behavior of IDEs.
It will try to automatically detect the absolute path of this directory and will report its determination (see
"Installation and initial set-up").
Input parameters:
Currently ChromaStarPy is necessarily a unified atmosphere and spectrum modeling code in that it
re-computes a new atmospheric model each time, even if only the spectrum synthesis or two-level-atom parameters
are changed. However, if specSynMode = True in the Input.py file, it will adopt the structure in Restart.py
and limit itself to just one iteration of the structure equations.
All parameters for all aspects of the modeling AND post-processing are imported from a module (a python
source file) in the run directory called Input.py. The sample *.py files in the Input/ directory that ships with
the installation can be simply copied to Input.py in the main installation/run directory.
Structure of Input.py:
See sample of Input.py content at end of this file.
Because Input.py is imported as a python source file, the input parameters are set by python variable
assignment statements. As a result, the input procedure will work regardless of the order of the parameters,
number and location of blank lines, and discretionary comment statements. The default format of the sample input
files is simply for purposes of readability. The default format is divided into six sections that are denoted
with a descriptive header that begins with a hash (#) symbol.
#Custom filename, #Default plot, #Spectrum synthesis mode
Includes two string variables, project, and runVers, that the user can set to create distinct file
names to distinguish model runs that would otherwise have indistinct names (see "Outputs" section).
Includes a string variable, makePlot, that determines which of six build-in plotting routines will be
executed for the default graphical display. If specSynMode = True, ChromaStarPy will adopt the atmospheric
structure in input module Restart.py and only perform one structure iteration before computing the synthetic
spectrum.
#Model atmosphere
Includes three basic input parameters needed to specify a spherical gravitating blackbody. Two of these
are needed to specify an un-blanketed plane-parallel static 1D atmosphere.
Additional parameters as needed to specify the overall abundance distribution, to vary key groups of
elements from the scaled-solar distribution, to tune the level of the background continuum opacity, etc.
#Spectrum synthesis
Includes parameters for the synthesis range, the minimum oscillator strength, line broadening enhancement,
and macroscopic broadening parameters. (Note that voigtThresh is currently not used - all lines are treated
with Voigt profiles.)
#Performance vs realism
Parameters for managing the balance between modeling realism and execution speed. Includes the number
of outer and inner iterations of the atmospheric structure calculation, and whether TiO JOLA bands are included.
#Gaussian filter for limb darkening curve, Fourier transform
This is for post-processed "data products" associated with observing the model through a Gaussian
narrow band filter. The wavelength and band-width of the filter may be adjusted here.
#Two-level atom and spectral line
Parameters for a user-defined atomic species with two bound energy levels and the one bound-bound
transition thereof. All atomic data that specify the energy level structure, the ionization stage,
and the line transition parameters.
#
Planetary transit parameters
Parameters that determine with exo-planet transit lightcurve
Spectrum synthesis mode:
If the parameter specSynMode = False ChromaStar.py will perform the number of outer and inner iterations of
the atmospheric structure equtions specified by input parameters nOuterIter and nInnerIter before
synthesizing the spectrum.
If specSynMode = True the code will adopt the structure specified with python assignments statements in
the source file (python module) Restart.py, and will only perform one outer and inner structure iteration
before proceeding to spectrum synthesis. This allows for rapid spectrum synthesis experiments in the case
where a converged structure has already been computed.
** Note: ChromaStarPy automatically writes the current structure to the *_restart.py file in the Outputs
directory (see "outputs" section) each time, and the user must manually copy the desired *_restart.py file to
Restart.py in the run directory (see "Inputs" directory).
Restart.py
This source file must always be present and contains an atmospheric model structure as python assignment
statements. When running with 'specSynMode = True' (see above), the user must manually ensure that the desired
atmospheric structure is contained in Restart.py. This can be done by copying the *_restart.py file (see "Outputs"
section) from the relevant structure run.
**
** Output files
**
All output files are created in the Outputs/ directory in the installation/run directory (see the absPath
environment variable in "Installation and initial set-up").
ChromaStarPy automatically creates six output files for each run. Each of these has several lines of
header that specify the modeling parameters, describe the units, and label the columns. The filenames for a
given run are distinguished from each other by the filename stem, as described below, and are generally
distinguished from those of other runs by a string that contains the user-defined values of the 'project'
and 'runVers' string variables (see "Input parameters" under "Setting up a modeling run"), and by the values
of the main atmospheric modeling parameters (Teff, logg, [A/H]) and spectrum synthesis parameters (starting
and ending wavelengths). All output files have the *.txt extension so as to be recognizable by simple editors
under Windows.
File: *.struc.txt: The tabulated atmospheric structure ("Report 1")
*.sed.txt: The absolute overall spectral energy distribution (SED) ("Report 2")
*.spec.txt: The continuum rectified synthetic spectrum for the user-specified wavelength range,
AND the line center wavelengths and line identification strings for the lines that
were included in the synthesis ("Report 3")
*.ldc.txt: The disk-centred limb-darkening curve of the model as observed with the user-defined
Gaussian filter, and the discrete Fourier cosine transform of the full diameter limb
darkening profile, and the spectrum of monochromatic continuum linear limb darkening
coefficients (LDCs) ("Report 4")
*.tla.txt: The continuum rectified spectral line, and the atomic energy-level populations of the
user-defined two-level atom (TLA) ("Report 5")
*_retart.py The stellar parameters and converged structure are written as python assignment statements.
This file is automatically input as a module, and whether the structure it contains is
used depends on the value of the input parameter specSynMode (see "Input parameters:"
under ("Setting up a modeling run").
*.ppress.txt Partial pressures of all atmoic, ionic, and molecular species that are treated in
Phil Bennett's integrated EOS/Checmical Equilibrium package "GAS" ("Report 6")
*.trans.txt Lightcurves in the Johnson-Cousins UBVRIK bands and the analytic lightcurve
of Mandel & Agol 2002 for comparison
**
** Integrated post-processing, reporting, and visualization
**
The application automatically imports matplotlib.pyplot() as plt() and automatically plots one of six
different outputs depending on the choice of the input parameters makePlot (see "Input parameters:" under
"Setting up a modeling run").
All variables declared in the main ChromaStarGasPy.py file are available for printing or plotting at the
console prompt, and the most useful ones have been given descriptive names using camelCase (note that
python names are case-sensitive). The user can identify the names of variables that hold the crucial
distributions by inspection of the output blocks of code that write the standard output files (see "Output
files"). These output blocks can be found by searching for the string "Report n", where "n" currently
ranges from 1 to 7.
Four output blocks are located after the main atmospheric and spectrum modeling code:
Report 1 block: Atmospheric structure distributions (writes to *.struc.txt file).
Report 2 block: Spectral energy distribution (SED) (writes to *.sed.txt file).
Report 3 block: Synthetic spectrum and line identifications (writes to *.spec.txt file)
Report 4 block: Tuneable narrow-band limb darkening curve and its Fourier transform (writes to
*.ldc.txt file), and spectrum of monochromatic linear limb darkening coefficients (LDCs)
One output block is found after the user-defined two-level atom section of the code:
Report 5 block: Spectral line profile and atomic energy level populations of user-defined two-level
atom (writes to *.tla.txt file)
Report 6 block: Found after Report 4 block: Log10 partial pressures for 105 species, including 51 molecules
computed by Phil Bennett's multi-D linearization package "GAS" - now integrated with ChromaStarPy
(writes to *.ppress.txt file)
Report 7 block: Lightcurves in the Johnson-Cousins UBVRIK bands and the analytic lightcurve
of Mandel & Agol 2002 for comparison (writes to *.trans.txt file)
**
**
** Atomic line list
**
**
ChromaStarPy ships with ascii and byte-data versions of a default line list with ~26000 lines spanning 260 to
2600 nm drawn from the on-line NIST Atomic Spectra Database (Kramida, A., Ralchenko, Yu., Reader, J., and NIST ASD
Team, 2015, NIST Atomic Spectra Database (ver. 5.3), [Online]. Available: http://physics.nist.gov/asd
[2015, November 26]. National Institute of Standards and Technology, Gaithersburg, MD.
The utility program LineListPy.py ships with the source tarball. It may be used to produce a byte-data
line list suitable for reading by ChromaStarPy from an input ascii line list as output by the on-line NIST Atomic
Spectra Database.
CAUTION: The output options of the NIST database interface must be selected so as to produce output with select
fields and units that match the ascii sample. Additionally, special characters that appear in some output
fields of the raw NIST ascii output (eg. '[', ']', '(', ')', '+', etc.) must be manually removed.
--------------------------------------------------------------------------------------
Sample Input.py file for the Sun and Earth (see "Setting up a modeling run" section)
#
#
#Custom filename tags to distinguish from other runs
project = "SunEarth"
runVers = "Test"
#Project specific notes:
# Test case:
# Star: Sun
# Spectrum: Na I D region
# Lightcurve: Earth, in plane of ecliptic
#Default plot
#Select ONE only if plotting 'inline' -
makePlotStruc = True
makePlotSED = True
makePlotSpec = True
makePlotLDC = True
makePlotFT = True
makePlotTLA = True
makePlotTrans = True
makePlotPPress = True
#Chemical species for partial rpessure plot:
plotSpec = "H"
#Spectrum synthesis mode
# - uses model in Restart.py with minimal structure calculation
specSynMode = True
if (specSynMode):
runVers += "SS"
#Model atmosphere
teff = 5777.0 #, K
logg = 4.44 #, cgs
log10ZScale = -0.0 # [A/H]
massStar = 1.00 #, solar masses
xiT = 1.0 #, km/s
logHeFe = 0.0 #, [He/Fe]
logCO = 0.0 #, [C/O]
logAlphaFe = 0.0 #, [alpha-elements/Fe]
#Spectrum synthesis
lambdaStart = 588.5 #, nm
lambdaStop = 589.5 #, nm
fileStem = project + "-"\
+ str(round(teff, 7)) + "-" + str(round(logg, 3)) + "-" + str(round(log10ZScale, 3))\
+ "-" + str(round(lambdaStart, 5)) + "-" + str(round(lambdaStop, 5))\
+ "-" + runVers
lineThresh = -3.0 #, min log(KapLine/kapCnt) for inclusion at all - areally, being used as "lineVoigt" for now
voigtThresh = -3.0 #, min log(KapLine/kapCnt) for treatment as Voigt - currently not used - all lines get Voigt
logGammaCol = 0.5 # Logarithmic VdW damping enhancement
logKapFudge = 0.0 # continuum opacity fudge factor
macroV = 1.0 #, macroscopic broadening dispersion km/s
rotV = 2.0 #, equatorial surface rotational velocity km/s
rotI = 90.0 #, inclination of rotational axis AND orbital axis degrees
RV = 0.0 #, system radial velocity km/s
vacAir = "vacuum" # wavelength scale ('air' OR 'vacuum')
sampling = "fine" # density of freq points in spectrum synthesis ('fine' is useful, 'coarse' for quick checking)
#Performance vs realism
nOuterIter = 12 #, no of outer Pgas(HSE) - EOS - kappa iterations
nInnerIter = 12 #, no of inner (ion fraction) - Pe iterations
ifMols = 1 #, whether to include TiO JOLA bands in synthesis
#Gaussian filter for limb darkening curve (LDC), fourier transform (FT)
diskLambda = 500.0 #, Band centre wavelength nm
diskSigma = 0.01 #, Band dispersion nm
#Two-level atom and spectral line
#Example: NaI D lambda 5896:
userLam0 = 589.592 #, nm
userA12 = 6.24 #, A_12 logarithmic abundance = log_10(N/H_H) = 12
userLogF = -0.495 #, log(f) oscillaotr strength // saturated line
userStage = 0 #, ionization stage of user species (0 (I) - 3 (IV)
userChiI1 = 5.139 #, ground state chi_I, eV
userChiI2 = 47.29 #, 1st ionized state chi_I, eV
userChiI3 = 71.62 #, 2nd ionized state chi_I, eV
userChiI4 = 98.94 #, 3rd ionized state chi_I, eV
userChiL = 0.0 #, lower atomic E-level, eV
userGw1 = 2 #, ground state state. weight or partition fn (stage I) - unitless
userGw2 = 1 #, ground state state. weight or partition fn (stage II) - unitless
userGw3 = 1 #, ground state state. weight or partition fn (stage III) - unitless
userGw4 = 1 #, ground state state. weight or partition fn (stage IV) - unitless
userGwL = 2 #, lower E-level state. weight - unitless
userMass = 22.9 #, amu
userLogGammaCol = 1.0 #, log_10 Lorentzian broadening enhancement factor
#Planetary transit parameters for transit light curve modelling
# ** Also depends on rotI chosen above!!
# Oribital period is not a free parameter - it is set by the
# size of the orbit and the planet's mass by basic form of
#Kepler's 3rd law
rJupiter = 11.21 # Earth radii - handy reference
ifTransit = True # set to True if we want an exoplanet lightcurve
#Data source: Wikipedia for now...
rOrbit = 1.00 # AU
rPlanet = 1.00 #Earth radii
#mPlanet = 1.0 #Earth masses #not needed (yet?)