pci-py scripts

In this section, we describe supplementary python scripts used to automate the entire pCI process, from the generation of basis sets and configuration lists to the actual calculations themselves. These python scripts read a user-defined YAML-formatted configuration file config.yml to set various parameters defining the atomic system of interest, as well as the types of the calculations to perform.

These python scripts are currently designed primarily for massive data generation via CI+all-order and CI+MBPT calculations on the UD clusters. They can be modified for more general calculations.

config.yml

The config.yml file is a YAML-formatted configuration file that defines important parameters of the atomic system of interest. This config file is divided into several sections, which are read by different scripts:

system parameters
HPC parameters
atomic system parameters
parameters used by basis programs
parameters used by add program
parameters used by conf program
parameters used by dtm program
parameters used by pol program
optional parameters

The system parameters are in the block system and is read by all python scripts:

system:
    bin_directory: ""
    generate_directories: True
    run_codes: True
    on_hpc: True
    pci_version: default

The system.bin_directory field specifies a path to a directory of pCI executable programs. If left blank, it is assumed the directories to the executable programs are in the user’s environment PATH.
The system.generate_directories field specifies whether or not to generate directories for calculations.
The system.run_codes field specifies whether or not the pCI programs should be run during the Python script execution. If set to False, the scripts will only generate the input files for the respective programs.
The system.on_hpc field specifies whether the user is running on an HPC environment. Setting this to True will create scripts that are submitted to the job scheduler (this is only compatible with the SLURM workload manager).
The system.pci_version field specifies which version of pCI to use from the HPC environment (this is relevant only for job scripts on HPC).

The HPC parameters are in the block hpc and is read by all python scripts if system.on_hpc=True:

hpc:
    partition: large-mem
    nodes: 1
    tasks_per_node: 64
    submit_job: False

The hpc.partition field specifies the name of the partition.
The hpc.nodes field specifies the number of nodes to utilize.
The hpc.tasks_per_node field specifies the number of tasks per node to utilize.
The hpc.submit_job field specifies whether to submit the batch job or not.

The job scripts generated by the included Python scripts are based on the SLURM workload manager. Users should customize the gen_job_script.py script to suit the system they are using for calculations.

The atomic system parameters are in the block atom and is read by all python scripts:

atom:
    name: Sr
    isotope:
    include_breit: True
    code_method: [ci+all-order, ci+second-order]

The atom.name field specifies the name of the atomic system.
The atom.isotope field specifies the isotope number. If left blank, the script will automatically find the atomic weight from the nuclear charge radii table of Ref.~cite{nucrad}. This feature requires the atom.name field to contain a valid atomic symbol.
The atom.include_breit field specifies whether or not to include the Breit interaction in calculations.
The atom.code_method field specifies the calculation method to utilize. Available options are ci, ci+all-order, and ci+second-order for pure CI, CI+all-order, and CI+MBPT, respectively. Users can input ci+all-order, ci+second-order to run both CI+all-order and CI+MBPT calculations concurrently.

basis.py

The basis.py script automates the basis set construction for the CI computations. By running the script, the basis set programs are run, resulting in HFD.DAT, which can be used by the next script for the CI calculations. In addition to the system block, it also reads the basis block:

basis:
    cavity_radius: 70
    diagonalized: False
    orbitals:
        core: 1s 2s 2p 3s 3p 3d 4s 4p
        valence: 5s 5p 4d 6s 6p 5d 7s 7p 6d
        nmax: 35
        lmax: 5
    b_splines:
        nmax: 40
        lmax: 6
        k: 7
    val_aov:
        s: 5
        p: 5
        d: 5
        f: 3
    val_energies:
        kval: 1
        energies:
            s: -0.28000
            p: [-0.22000, -0.22000]
            d: [-0.31000, -0.31000]
            f: [-0.13000, -0.13000]

The basis.cavity_radius field specifies the size of the spherical cavity in a.u.
The basis.diagonalized field specifies whether to diagonalize the basis set or not.
The basis.orbitals block specifies the core and valence orbitals to be included in the basis. It also requires a maximum principal quantum number nmax and maximum partial wave lmax for basis set orbital generation.
The basis.b_splines block specifies the maximum principal quantum number nmax (number of splines), maximum partial wave lmax, and order of the splines k.
The basis.val_aov block specifies the number of valence orbitals to include for each partial wave in the all-order computations.
The basis.val_energies block specifies the energies of the valence orbitals. kval=1 is the default choice, where energies are set to the DHF energy of the lowest valence \(n\) for the particular partial wave. In this case, the field energies can be safely ignored. kval=2 allows specified energies of the valence orbitals, but is only used when the all-order valence energies are severely divergent.

In addition, the script will read the optional block:

optional:
    qed:
        include: False
        rotate_basis: False

    isotope_shifts:
        include: False
        K_is: 1
        C_is: 0.01

The optional.qed block allows users to specify inclusion of QED corrections (this is currently not supported).
The optional.isotope_shifts block allows users to specify isotope shift calculations by switching the include value to True and specifying keys K_is and C_is.

The basis.py script also writes the standard output of the executables to their respective *.out files, e.g. hfd standard output is written to the file hfd.out.

ci.py

The ci.py script automatically generates the list of configurations given information about the atomic system of interest via a configuration file config.yml. Note that if BASS.INP is not present, the order of the conigurations will be by \(nl\), and not how it is defined in the basis set construction. This script reads the add block:

add:
    # Lists of even and odd parity reference configurations
    ref_configs:
        odd: [5s1   5p1]
        even: [5s2]
    basis_set: 22spdfg
    orbitals:
        core: 1s 2s 2p 3s 3p 3d 4s 4p
        active: [
            4-7p:  0  4,
            4-7d:  0  4,
            4-7f:  0  4,
            5-7g:  0  4,
            ]
    excitations:
        single: True
        double: True
        triple: False

The add.ref_configs block requires a list of reference configurations to excite electrons from to construct the list of configurations defining the CI space. The list will not be constructed if left blank for a specified parity.
The add.basis_set block requires specification of the basis set designated by nspdfg, where n specifies the principal quantum number, and spdfg specifies inclusion of \(s\), \(p\), \(d\), \(f\), and \(g`\) orbitals. One can include higher partial waves by appending to the end of the list h, i, k, …
The add.orbitals block allows full customization of allowed orbital occupancies. For example, 1-2s: 2 2 defines the 1s and 2s orbitals to be closed, 2p: 6 6 defines the 2p orbital to be closed, 3-7p: 0 6 defines 3p to 7p orbitals to be completely open to allow up to 6 electrons on those orbitals.
The add.excitations block defines the types of excitations allowed by setting the sub-fields to be True or False.

This script also reads parameters for the CI execution from the conf block:

conf:
    odd:
        J: 1.0
        JM: 1.0
        J_selection: False
        num_energy_levels: 12
        num_dvdsn_iterations: 50
    even:
        J: 0.0
        JM: 0.0
        J_selection: False
        num_energy_levels: 24
        num_dvdsn_iterations: 50
    include_lsj: True
    write_hij: True

For each parity, * The conf.parity.J field defines the total angular momentum of the energy levels. * The conf.parity.JM field defines the projection of the total angular momentum. * The conf.J_selection field defines whether the user wants energy levels of a specific \(J\) value defined by J and JM. * The conf.parity.num_energy_levels field defines the number of energy levels to be calculated for the respective parity. * The conf.parity.num_dvdsn_iterations field defines the total number of Davidson iterations to allow for the respective parity. * The conf.include_lsj field defines whether the user wants expectation values \(L^2\) and \(S^2\) to be calculated. * The conf.write_hij field defines whether the user wants the Hamiltonian matrix to be written to file CONFp.HIJ.

If system.generate_directories or system.run_codes is set to True, the ci.py script will generate directories for the CI calculations based on the parity and \(J\) value specified. In the sample provided above, the directories odd1 and even0 will be generated for odd-parity calculations for \(J=1\) levels and even-parity calculations with \(J=0\) levels, respectively.

dtm.py

The dtm.py script automates the matrix element calculations. Specifically, this script prepares directories for calculations with pdtm by moving the relevant input files from previous calculations to them. This script reads the dtm block from config.yml:

dtm:
    include_rpa: True
    DM:
        matrix_elements:
        level_range:
            odd:
            even:
    TM:
        matrix_elements: E1
        from:
            parity: odd
            level_range: 1 3
        to:
            parity: even
            level_range: 1 1

The dtm.include_rpa field defines whether the user would like to include RPA corrections. Note that this option requires compilation of the rpa and rpa-dtm programs.
The dtm.DM field defines job parameters for density matrix (DM) calculations, while dtm.TM defines job parameters for transition matrix (TM) calculations.
The dtm.*.matrix_elements defines operators to include RPA if include_rpa = True. This value can be a single matrix element or an array of matrix elements. In addition, a separate file *.RES will be generated by pdtm for each operator listed here. For DM, the operators include: GF, A_hf and B_hf. For TM, the operators include: E1_L, E1_V, E1, E2, E3, M1, M2, M3, EDM, PNC, AM, MQM. To include multiple operators, list the operators in brackets, e.g. [E1, M2].
The dtm.*.level_range defines the level ranges to calculate matrix elements. The indices of each energy level can be found in the file FINAL.RES or CONF.RES generated by the pconf program. DM calculations require one of the two parities (odd or even) to be filled with a level range. TM calculations require all fields TM.from.* and TM.to.* to be filled with the respective parities, as well as the initial and final level ranges of the transitions.

pol.py

The pol.py script automates polarizability calculations. This script reads the pol block:

pol:
    parity: even
    level: 1
    method: 1
    field_type: static, dynamic
    wavelength_range: 1000 1000
    step_size: 0

The pol.parity field specifies the parity of the state to calculate polarizabilities for.
The pol.level field specifies the index of the state to calculate polarizabilities for.
The pol.method field specifies the method to calculate polarizabilities. This field corresponds to the integer parameter Method described here.
The pol.field_type field specifies calculations of static or dynamic polarizabilities. Calculations of both can be done by setting this field to [static, dynamic].
The pol.wavelength_range field specifies the range of wavelengths to calculate dynamic polarizabilities for.
The pol.step_size field specifies the step size of the range of wavelengths.

gen_portal_csv.py

The gen_portal_csv.py script generates csv-formatted datafiles of atomic energy levels and matrix elements given output files from conf and dtm runs. This script reads the portal block from config.yml:

portal:
    ignore_g: True
    min_uncertainty: 1.5

The portal.ignore_g field removes all atomic properties with \(>g\) in the configuration or \(>G\) terms.
The portal.min_uncertainty field sets a minimum uncertainty in percentage for matrix value uncertainties. The script has predefined minimum uncertainties set for a few systems.

calc_lifetimes.py

The calc_lifetimes.py script generates csv-formatted datafiles of lifetimes and transition rates given output files from gen_portal_csv.py.

More information about atomic data generation for the UD ATOM portal can be found here.