API

This document is the full description of user API. It should serve as a reference for anyone using the GainCalculator. Although there are some code examples, these are very limited and only serve to demonstrate concepts. If you are new to GainCalculator you should consider reading Getting started. If you are looking for more code examples please visit Usage examples.

The API consists of several classes listed below:

init(logging_handler=<logging.FileHandler object>)[source]

Must be called anytime you want to use gain_calculator, preferably in main calling script

class EnergyLevel(config)[source]

This class represents a single energy level. Initialize it like this:

EnergyLevel(config="1s+2(0)0 2s+2(0)0 2p-2(0)0 2p+3(3)3 3s+1(1)4")
Parameters:config (str) – A sequence of terms separated by space each representing single shell in jj coupling notation. A shell 5p+3(1)2 has principal quantum number \(n=5\), orbital quantum number \(l = p\). There are three electrons in this shell. The number in brackets is 2 times the total angular momentum \(2J\). Here \(2J\) is 1 hence \(J\) is \(\frac{1}{2}\). The last number is 2 times total angular momentum when taking into account all previous shells here it is 2 meaning total angular momentum of the whole configuration up to this shell is 1.
Variables:degeneracy (int) – A number representing the degeneracy of the level. It is usually denoted \(g\).
class Atom(symbol, config_groups, data_folder)[source]

This class represents a specific atom with given configuration. Initialize it like this:

Atom(
    symbol="Fe",
    config_groups=ConfigGroups(
        base="1*2 2*8",
        max_n=4
    ),
    data_folder = "./data",
    log = lambda: current, total: print "{}% done".format(current / total * 100)
)
Parameters:
  • symbol (str) – A symbol of the element, eg. “Ge” for germanium
  • config_groups (ConfigGroups) – Instance of class ConfigGroups representing possible shell configurations. For more info see ConfigGroups.
  • data_folder (str) – Folder where the atomic data are stored, if it doesnt exist, it will be created
get_combined_populations(energy_level, temperatures, electron_densities, population_total=1.0, log=None)[source]

Convenience wrapper around get_populations with combine parameter set to itertools.product. Thus it performs the calculation over all possible combinations of temperature and density.

Parameters:
  • energy_level (EnergyLevel) – the energy level instance
  • temperatures (ndarray) – temperature in eV (could be iterable)
  • electron_densities (ndarray) – electron density in cm^-3 (could be iterable)
  • population_total (float) – 1 by default
  • log (func) – Function that get called each time an iteration is made. The passed arguments are current index

of the iteration and total length of the iteration. The function is None by default, meaning none is called. :return: numpy structured array with named fields population, electron_density and temperature**

get_populations(energy_level, temperatures, electron_densities, combine, population_total=1.0, log=None)[source]

Get electron population on single energy level at given temperature and electron density given by arrays/lists. The calculation will be done over the list of tuples generated by applying combine on temperatures and electron_densities. The calculation is done for all energy levels in given atom. Population total is the sum of populations of all energy levels. By default this is 1 and the function returns relative populations. Eg. 0.1 means 10% of all electrons are at energy_level. Example usage:

atom = Atom(
    symbol="Fe",
    config_groups=ConfigGroups(
        base="1*2 2*8",
        max_n=4
    )
)
result = atom.get_population(
    energy_level=EnergyLevel(config="1s+2(0)0 2s+2(0)0 2p-2(0)0 2p+3(3)3 3s+1(1)4"),
    temperatures=[900.0, 1000.0]  # eV
    electron_densities=[1e20, 1e21]  # cm^-3
    combine=itertools.product
)
result["population"]  # this is an array of populations,
len(result["population"]) == 4  # True
Parameters:
  • energy_level (EnergyLevel) – the energy level instance
  • temperatures (ndarray) – temperature in eV (could be iterable)
  • electron_densities (ndarray) – electron density in cm^-3 (could be iterable)
  • combine (function) – Function taking two lists and returning a single list of tuples
  • population_total (float) – 1 by default
  • log (func) – Function that get called each time an iteration is made. The passed arguments are current index

of the iteration and total length of the iteration. The function is None by default, meaning none is called. :return: numpy structured array with named fields population, electron_density and temperature

class ConfigGroups(base, max_n)[source]

This class represents a set of all possible shell configurations up to max_n concerning only the number of electrons in each shell given by principal quantum number n. There is no end user use of this class aside from providing its instance as a param to other classes. Initialize it like this:

ConfigGroups(
    base="1*2 2*8",
    max_n=4
)
Parameters:
  • base (str) – The base configuration from which all config groups are generated. Notation “1*2 2*8” means there are 2 electron in shell with \(n=1\) and 8 electrons in shell with \(n=2\). Notation with asterisks and spaces must be used at all times.
  • max_n (int) –

    Maximal principal quantum number \(n\) up to which ConfigGroups are represented:

    ConfigGroups(base=1*2 2*8, max_n=4)

    represents:

    ["1*2 2*8", "1*2 2*7 3*1", "1*2 2*7 4*1"]
class Transition(atom, lower, upper)[source]

This class represents a transition between upper and lower energy levels. Initialize it like this:

atom = Atom(
    symbol="Fe",
    config_groups=ConfigGroups(
        base="1*2 2*8",
        max_n=4
    )
)
Transition(
    atom=atom,
    lower=core.EnergyLevel("1s+2(0)0 2s+2(0)0 2p-1(1)1 2p+4(1)1 3s+1(1)2"),
    upper=core.EnergyLevel("1s+2(0)0 2s+2(0)0 2p-1(1)1 2p+4(6)1 3p+1(3)4")
)
Parameters:
  • atom (Atom) – The atom instance in which te transition occurs
  • lower (EnergyLevel) – The lower energy level
  • upper (EnergyLevel) – The upper energy level
Variables:

weighted_oscillator_strength (float) – The weighted oscillator strength of the transition \(gf\).
get_populations(temperatures, electron_densities, population_total=1.0)[source]

Simple convenience wrapper around EnergyLevel.get_population() to get both lower and upper energy levels populations.

Parameters:
  • temperatures (ndarray) – temperature in eV
  • electron_densities (ndarray) – electron density in cm^-3
  • population_total (float) – 1 by default
Returns:

a dict with two keys: {upper: …, lower: …} - the values are numpy structured arrays with fields temperature, electron_density and population
print_progress(iteration, total, prefix='', suffix='', decimals=1, bar_length=100)[source]

A helper function to be called in a loop to create terminal progress bar. Could be used for example to display progress of population calculation.

Parameters:
  • iteration (int) – current iteration
  • total (int) – total iterations
  • prefix (str) – prefix string, ‘’ by default
  • suffix (str) – suffix string
  • decimals (int) – positive number of decimals in percent complete
  • bar_length (int) – character length of bar