YALIP 0.9.4

Python 3 package to calculate the energy levels of lanthanide ions.

YALIP 0.9.4 (Yet Another Lanthanide Ion Package)

This is a Python 3 package to calculate the energy levels of multi-electron systems populating the 4f configuration, which means the lanthanide or rare-earth ions from Ce³⁺ (4f¹) to Yb³⁺ (4f¹³). The calculation is based on Racah's tensor algebra using an approach introduced in my PhD thesis [1] and advanced in [2]. You find a copy of the thesis and corrections in the folder docs. The original version of the software is available in the GitHub repository Lanthanide-0.3 and the last implementation of the original approach in the repository Lanthanide. However, instead of computing its numerical operator matrices, the YALIP package is using the matrix elements from the Zenodo repository AMELI calculated and stored in exact arithmetic according to [2].

Installation

The package is available on PyPI and the installation therefore is possible using pip

pip install yalip

Usage

The YALIP package provides raw access to the exact matrices from the AMELI repository as SymPy.SparseMatrix objects via the functions get_symbolic_matrix(name, config, state_space) and get_symbolic_transform(config). However, it is mainly designed for three use cases on different abstraction levels.

1. Class States

Access to raw numerical representations of states and operator matrices from the AMELI repository is provided by the class States. The following code initialises all basis states of the Pr³⁺ ion in $SLJ$ coupling:

from yalip import States, Coupling

config = "f2"
coupling = Coupling.SLJ

states = States(config, coupling)

2. Class Levels

Calculation of states in intermediate coupling, their energy levels and radiative transitions based on given radial integrals and Judd-Ofelt parameters is provided by the class Levels. Typical initialisation code for a Pr³⁺ ion looks like:

from yalip import Cauchy, Coupling, Levels

config = "f2"
coupling = Coupling.SLJ
radial = {"base": 327.39, "H1/2": 68576.05, "H1/4": 49972.76, "H1/6": 32415.29, "H2": 728.18,
          "H3/0": 16.99, "H3/1": -417.98, "H3/2": 1371, "H5fix": 0.19, "H6fix": 1.67}
jo = {"JO/2": 1.981, "JO/4": 4.645, "JO/6": 6.972}
material = Cauchy(1.35123e-5, 2.94780e-3, 1.49985, -1.30933e-3, -3.23335e-6)

ion = Levels(config, coupling, radial, jo, material)

3. Class Fits

The class Fits is used to perform energy level and Judd-Ofelt fits to determine optimised radial integrals and Judd-Ofelt parameters matching a measured absorption spectrum. Typical initialisation code for a Pr³⁺ ion looks like:

from yalip import Cauchy, Coupling, Fits

config = "f2"
coupling = Coupling.SLJ
radial = {"base": 327.39, "H1/2": 68576.05, "H1/4": 49972.76, "H1/6": 32415.29, "H2": 728.18,
          "H3/0": 16.99, "H3/1": -417.98, "H3/2": 1371, "H5fix": 0.19, "H6fix": 1.67}
material = Cauchy(1.35123e-5, 2.94780e-3, 1.49985, -1.30933e-3, -3.23335e-6)

opt = Fits(config, coupling, radial, material)

Example Scripts

Some application example scripts are available in the folder run.

Parameter Sets

The YALIP package provides some sets of radial integrals and Judd-Ofelt parameters of lanthanide ions as well as spectral refractive index parameters for some materials from the literature. For details see the source code of lanthanide.py.

Logging

The YALIP package uses the logger package for status messages. The following code example provides a basic setup to make these messages visible on the console:

import logging
from yalip import Coupling, States

logger = logging.getLogger("my_script")

def init_logger(level=logging.INFO):
    root = logging.getLogger()
    root.setLevel(level)
    log_format = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")

    console_h = logging.StreamHandler()
    console_h.setFormatter(log_format)
    console_h.setLevel(level)
    root.addHandler(console_h)

if __name__ == "__main__":
    init_logger(level=logging.DEBUG)

    config = "f2"
    coupling = Coupling.SLJ
    
    states = States(config, coupling)

Caching

The YALIP package uses platformdirs.user_cache_dir() to create a cache folder for files from the AMELI repository and another one for converted floating point matrices. YALIP regularly checks the repository for new versions, but at most twice a day.

A local HDF5 cache file is used to store converted matrices. Used matrices are also cached in the memory (functools.lru_cache).

License

This is free software under the MIT License.

References

[1] Reinhard Caspary: "Applied Rare-Earth Spectroscopy for Fiber Laser Optimization", doctoral dissertation at Technische Universität Braunschweig, published with Shaker, Aachen, 2002

[2] Reinhard Caspary: "AMELI: Angular Matrix Elements of Lanthanide Ions", arXiv, 2026, https://doi.org/10.48550/arXiv.2603.21947