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?)