From 46872369a4e93e00ea64482fb74c9efd4a420c94 Mon Sep 17 00:00:00 2001 From: "Knox S. Long" Date: Sun, 29 Oct 2023 15:36:06 -0500 Subject: [PATCH] Documenation (and better diag for MacroAtoms) --- .../source/atomic/bound_free_topbase.rst | 20 +++ docs/sphinx/source/atomic/elem_ions.rst | 117 +++++++++++------- 2 files changed, 92 insertions(+), 45 deletions(-) diff --git a/docs/sphinx/source/atomic/bound_free_topbase.rst b/docs/sphinx/source/atomic/bound_free_topbase.rst index 7ca5f24b2..b06a88815 100644 --- a/docs/sphinx/source/atomic/bound_free_topbase.rst +++ b/docs/sphinx/source/atomic/bound_free_topbase.rst @@ -80,9 +80,29 @@ The items that must match are: - the upper level, which will be a level in the next ion (ilv) - the lower level, which will be in the ion that is being photoionized + Comments ======== +**The upper level in the MacroAtom case** + +A common error that creates problems in reading in photoionization x-sections in the MacroAtom case is not to include the next ion up, partiulary the bare ion. If one encounters errors where the upper level is +not found, one should check the level file to verify that that the upper level ion is present, and that the inputs allow for the existence of at least the first level +of that ion. + +For example, if one wishes to read in photoionization x-sections for N VII (hydrogenic), the levels file should include lines like:: + + IonM N 7 7 2 667.05100 1000 5 1s(2S_{1/2}) + IonM N 7 8 1 1.0000e+20 1 1 Bare + +The following is incorect:: + + IonM N 7 7 2 667.05100 1000 5 1s(2S_{1/2}) + IonM N 7 8 1 1.0000e+20 0 0 Bare + +because although the bare ion is present, the maximum number of levels is set to 0. This is not an issue for the simple atom case. + + **Extrapolation to higher energies** Some topbase cross-sections do not extend to very high energies, for reasons that diff --git a/docs/sphinx/source/atomic/elem_ions.rst b/docs/sphinx/source/atomic/elem_ions.rst index 0fd36b8db..3df524e85 100644 --- a/docs/sphinx/source/atomic/elem_ions.rst +++ b/docs/sphinx/source/atomic/elem_ions.rst @@ -2,7 +2,7 @@ Elements and Ions ################# -The first file that must be read into \textsc{python} is the file that defines the elements and ions. The +The first file that must be read into **Python** is the file that defines the elements and ions. The Source: ======= @@ -16,50 +16,81 @@ Translation to python: The original data and the translation can be found in py\_verner. A simple awkscript converts the downloaded data to Python format. -Datafile - elem_ions_ver.py: -============================ +Data Format +=========== -There are two sections to the file, first elements are defined: +There are two sections to the file, first elements are defined -+--------+--+------+---------+-------------+ -|Label |z |Symbol|Abundance|Atomic Weight| -+--------+--+------+---------+-------------+ -|Element |1 | H | 12.00 | 1.007940 | -+--------+--+------+---------+-------------+ -|Element |2 | He | 10.99 | 4.002602 | -+--------+--+------+---------+-------------+ +The first portion of a typical file is as follows:: -and then the ions. (Abundances are generally defined logarithmically + # Source Verner, Barthel & Tytler 1994 A&AS 108, 287 + Element 1 H 12.00 1.007940 + Element 2 He 10.99 4.002602 + #Element 3 Li 3.31 6.941000 + #Element 4 Be 1.42 9.012182 + #Element 5 B 2.88 10.811000 + Element 6 C 8.56 12.011000 + Element 7 N 8.05 14.006740 + Element 8 O 8.93 15.999400 + + +And the columns are as follows + +* A label for this type of data entry +* The z of the elment +* The common abbreviation for the elemen +* The atomic weight of the element + +Lines beginning with # (and empty lines) are treated as comments. So in this case, Li, B and B are ignored, because +of their relatively low abundance. + +Abundances are generally defined logarithmically with respect to H at 12.00. In principle, there are two choices if one wished to defien a plasma where, for example, He was the dominant element. One could leave the H abundance at 12 and define the He abundance as for example 13.00 Alternatively, one could set the He -abundnace to 12.00 and define all of the other elements with respect +abundance to 12.00 and define all of the other elements with respect to this. Either choice should work but none has been tested. It is -unclear whether code will work at all for a plasma with no H.) - - -+------+-------+--+------+--+-----------+--------+---------+-------------+ -|Label |Symbol |z |state |g |:math:`\xi`|max lev |max nlte |. config | -+------+-------+--+------+--+-----------+--------+---------+-------------+ -|IonV | H |1 | 1 | 2| 13.59900 | 1000 | 10 | 1s(2S_{1/2})| -+------+-------+--+------+--+-----------+--------+---------+-------------+ -|IonV | H | 1| 2 |1 | 1.0000e+20| 0 | 0 | Bare. | -+------+-------+--+------+--+-----------+--------+---------+-------------+ -|IonV | He | 2| 1 | 1| 24.58800 |1000 | 10 | 1s^2(1S_0)$ | -+------+-------+--+------+--+-----------+--------+---------+-------------+ -|IonV | He | 2| 2 | 2| 54.41800 |1000 | 10 | 1s(2S_{1/2})| -+------+-------+--+------+--+-----------+--------+---------+-------------+ -|IonV | He | 2| 3 | 1|1.0000e+20 | 0 | 0 | Bare | -+------+-------+--+------+--+-----------+--------+---------+-------------+ - - -Here :math:`\xi` is clearly the ionizaton potential in eV, and max lev is the number -of levels that are allowed, if the ion is part of a simple atom, while -max nlte is the number that are allowed if the ion is part of a macro-atom. -Whether an ion is treated as part of a simple atom or as part of a macro-atom -is determined by what is read in as part of the level information. +unclear whether code will work at all for a plasma with no H. + + +The ion section (which could be in a separate file) has the following format:: + + IonV H 1 1 2 13.59900 1000 10 1s(2S_{1/2}) + IonV H 1 2 1 1.0000e+20 1 1 Bare + + IonV He 2 1 1 24.58800 1000 10 1s^2(1S_0) + IonV He 2 2 2 54.41800 1000 10 1s(2S_{1/2}) + IonV He 2 3 1 1.0000e+20 1 1 Bare + + +and the columns have the following meaning + +* Label for an ion that will be treated as a simple ion +* The common abbreviation for the element +* z of the ion +* ionization state of the ion +* g-factor for the ground state +* the ionizaton potential in eV +* maximum number of (simple) levels allowed +* maximum number of nlte (macro-atom) levels +* the configurations (which for information only) + +The label for the ion entries determines whether an element will be treated as simple atom or as a macro-atom. For case where H is to be treated as +a macro atom, but He is to be treated as a simple atom, this file would become:: + + + IonM H 1 1 2 13.59900 1000 10 1s(2S_{1/2}) + IonM H 1 2 1 1.0000e+20 1 1 Bare + + IonV He 2 1 1 24.58800 1000 10 1s^2(1S_0) + IonV He 2 2 2 54.41800 1000 10 1s(2S_{1/2}) + IonV He 2 3 1 1.0000e+20 1 1 Bare + +Note that only evident changed is the label, but in this case the number of nlte levels, and not the number of levels is what is important. + + Python structure: ================= @@ -68,14 +99,10 @@ This data is held in Python in various fields in structures **elements** and **i Comments: ========= -**Supernova models** - -Supernovae (SNe) do not have solar abundances. SS included an additional -file, \texttt{elem\_ions\_ver\_sn.py} for use with SN models. This is accessed -through the \texttt{standard\_sn\_kurucz} masterfile and as far as I know is -just added by hand to match expected Type Ia abundances and specifically -the abundances used by Tardis. +**Maximun numbers of levels** -ksl - The abundances used by Verner are not necessarily the best values today. This is one of the the items we should consider updating. +As indicated the numbers here are maximum values, and the actual numbers of levels for particular ion will depend on the data that follows. +One can use the numbers here to limit the complexity of, for example, a macro-atom to see whether making a more complicated macro-atom affects +the reusult of a calculation. One does not need to change the "downstream" data to make this happen, **Python** will simply ignore the extra +data. -Although the element data file described above includes the Atomic weight, this is not actually used as described in `issue 802 `_. The documentation needs to be updated when this is closed.