pyCELP (aka "pi-KELP"): a python package for Coronal Emission Line Polarization calculations.
Lead Developer: Tom Schad - National Solar Observatory
Code reference documentation available at tschad.github.io/pycle
**DISCLAIMER: pycelp is still in the early stages of development. Contributors are welcome. **
pyCELP is used to forward synthesize the polarized emission of ionized atoms formed in the solar corona. It calculates the atomic density matrix elements for a single ion under coronal equilibrium conditions and excited by a prescribed radiation field and thermal collisions. In its initial release, pyCELP solves a set of statistical equilibrium equations in the spherical statistical tensor respresentation for a multi-level atom for the no-coherence case. This approximation is useful in the case of forbidden line emission by visible and infrared lines, such as Fe XIII 1074.7 nm and Si X 3.9 um. See Schad & Dima 2020 for more details and specific references.
A read-only Enhanced PDF version of Schad & Dima 2020 is available via this link.
A read-only Enhanced PDF version of Schad & Dima 2021, regarding symmetry-breaking effects, is available via this link.
The original code developed by Schad & Dima 2020 (previously referred to as pyCLE) was a Fortran based code wrapped in python. pyCELP is a completely new implementation coded entirely in Python. It takes advantage of specific algorithm changes, numba jit compilers, and efficient numpy linear algebra packages to provide excellent speed performance that in most cases exceeds the earlier code. More information pertaining to numba is below.
If you use pyCELP, please reference Schad & Dima (2020). pyCELP is listed on the Astrophysics Source Code Library (ASCL) registry and its bibcode can be found on NASA/ADS.
Further references for the polarized theory include Casini & Judge (1999) and Landi Degl’innocenti & Landolfi (2004).
- python3, numpy, numba
- (optional - for tests/examples) matplotlib, scipy, jupyter
- (optional - for updating docs) pdoc3
- The CHIANTI atomic database is also required. Originally, this code was developed with Chianti v9; however, it is now upgraded to use Chianti v10. Chianti v9 should still work; however, there have been modifications in particular to the Si IX model that the update version and its example codes assume. pyCELP will automatically search for the Chianti atomic database path using the default environment variable XUVTOP.
It is recommended to install pycelp within a conda environment. For the best performance, it is recommended to use a version of numpy with an optimal linear algebra library, e.g. MKL for intel compilers (https://numpy.org/install/#numpy-packages--accelerated-linear-algebra-libraries).
Example:
$ conda create --name pycelp
$ conda activate pycelp
$ conda install python numpy scipy numba matplotlib$ git clone https://github.com/tschad/pycelp.git
$ cd pycelp
$ python setup.py develop Once the pyclep package is cloned or downloaded into a directory, it can be installed with the provided setup script either in develop or install mode. The above shows the develop mode installation which is useful when adding to the code.
Below is a minimal example of using the pycelp code from a python terminal. For more extensive examples, see those provided in the examples subdirectory within the project repo.
A tour of the main class can be seen in this notebook.
(juplab) [schad@Schad-Mac pycelp]$ python
Python 3.9.4 (default, Apr 9 2021, 09:32:38)
[Clang 10.0.0 ] :: Anaconda, Inc. on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import pycelp
>>> fe13 = pycelp.Ion('fe_13',nlevels = 50)
reading: /usr/local/ssw/packages/chianti/dbase/fe/fe_13/fe_13.elvlc
reading: /usr/local/ssw/packages/chianti/dbase/fe/fe_13/fe_13.wgfa
reading: /usr/local/ssw/packages/chianti/dbase/fe/fe_13/fe_13.scups
reading: /usr/local/ssw/packages/chianti/dbase/fe/fe_13/fe_13.psplups
using default abundances: /usr/local/ssw/packages/chianti/dbase/abundance/sun_photospheric_2009_asplund.abund
reading: /usr/local/ssw/packages/chianti/dbase/abundance/sun_photospheric_2009_asplund.abund
testing default file: /usr/local/ssw/packages/chianti/dbase/ioneq/chianti.ioneq
reading: /usr/local/ssw/packages/chianti/dbase/ioneq/chianti.ioneq
setting up electron collision rate factors
setting up proton collision rate factors
setting up non-dipole radiative rate factors
getting non-dipole rate factors
setting up dipole radiative rate factors
>>>
>>> fe13
pyCELP Ion class
---------------------
Ion Name: fe_13
Number of energy levels included: 50
Number of SEE equations: 142
Number of Radiative Transitions: 366
Ionization Equilbrium Filename: /usr/local/ssw/packages/chianti/dbase/ioneq/chianti.ioneq
>>>pyCELP uses numba @njit decorators for jit compiling many portions of the codebase. In most instances, the code adopts a file-based cache for storing compiled versions of the code for later use. The first time pyCELP is used, there is additional overhead in the time required to compile the code. Subsequent calls are significantly faster. If one makes modifications to the code and errors occur, it may be advised to delete the cached files the _pycache_ directory of the installed package.
The code does not use numba parallel options for multithreading.
Numba can be disabled through the use of an environmental variable (NUMBA_DISABLE) but this is not frequently used.
pyCELP uses numpy libraries which can have multithreaded modules. If pyCELP is used in a multiprocessor application, threads need to be properly managed.
Code reference documentation is available at tschad.github.io/pycle. These are created using pdoc3. They are easily manually built and/or updated from the main project repo directory by using the following command.
pdoc --html --force --output-dir docs pycelppyCELP evolved from work initially using the CLE code developed by Phil Judge and Roberto Casini at the High Altitude Observatory. While pyCELP is now a completely independent implementation, we express our gratitude for all we learned by using CLE. pyCELP has been developed based on the excellent treatise on spectral line polarization by Egidio Landi Degl’innocenti and Marco Landolfi available here.