Skip to content

Commit

Permalink
Documenation (and better diag for MacroAtoms)
Browse files Browse the repository at this point in the history
  • Loading branch information
@kslong
kslong committed Oct 29, 2023
1 parent c9000d8 commit 4687236
Show file tree
Hide file tree
Showing 2 changed files with 92 additions and 45 deletions.
20 changes: 20 additions & 0 deletions docs/sphinx/source/atomic/bound_free_topbase.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
117 changes: 72 additions & 45 deletions docs/sphinx/source/atomic/elem_ions.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
=======
Expand All @@ -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:
=================
Expand All @@ -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 <https://github.com/agnwinds/python/issues/802>`_. The documentation needs to be updated when this is closed.

0 comments on commit 4687236

Please sign in to comment.