API

Density fitting basis IO

salted.basis_client.BasisClient

Maintain a KSDFT basis data dataset (in yaml format), provide methods to read and write the dataset. The class will check the sanity of the dataset file when initialized, and check the consistency of the basis data when writing. This class will never keep the basis data in memory, but read and write the dataset file every time needed.

Usage: 

basis_client = BasisClient()        # instantiate the basis client
basis_data = basis_client.read("my_basis")       # read basis data
lmax, nmax = basis_client.read_as_old_format("my_basis")  # read basis data in the old format (see docstring)
basis_client.write("my_basis", {
    "H": {"lmax": 1, "nmax": [4, 3]}, "O": {"lmax": 2, "nmax": [5, 4, 3]}
})  # write basis data
basis_client.pop("my_basis")        # remove basis data

YAML structure: (indent with 2 spaces) 

my_basis_name:
  H:
    lmax: 1
    nmax: [4, 3]
  O:
    lmax: 2
    nmax: [5, 4, 3]

Python dict structure: 

{
    "my_basis": {
        "H": {
            "lmax": 1,
            "nmax": [4, 3]
        },
        "O": {
            "lmax": 2,
            "nmax": [5, 4, 3]
        }
    }
}

__init__(_dev_data_fpath=None)

Initialize the basis client with the data file path.

Parameters:

Name Type Description Default
_dev_data_fpath optional

For development only!!! Do not use this argument!!! The path to the dataset file. If not provided, the default dataset file will be used.

 None

__salted_package_root() property

Get the root directory of the salted package

check_sanity()

Check the sanity of the dataset file.

Current check: 1. If there are duplicated basis names (by yaml raising error) 2. lmax nmax consistency n. (plz add more checks here if needed)

pop(basis_name)

Pop basis data from the dataset file

read(basis_name)

Read basis data from the dataset file

read_as_old_format(basis_name)

Read basis data and return as the old format

Old format: 

lmax = {
    "H": 1,
    "O": 2
}
nmax = {
    ("H", 0): 4,
    ("H", 1): 3,
    ("O", 0): 5,
    ("O", 1): 4,
    ("O", 2): 3
}

write(basis_name, basis_data, force_overwrite=False)

Write basis data to the dataset file


Utility functions

salted.sys_utils.sort_grid_data(data)

Sort real space grid data The grid data is 2D array with 4 columns (x,y,z,value). Sort the grid data in the order of x, y, z.

Parameters:

Name Type Description Default
data np.ndarray

grid data, shape (n,4)

 required

Returns:

Type Description
np.ndarray

np.ndarray: sorted grid data, shape (n,4)


Input file IO

salted.sys_utils.ParseConfig

Input configuration file parser

To use it, make sure an inp.yaml file exists in the current working directory, and simply run ParseConfig().parse_input().

In our context, "input file" equals to "confiuration file", refers to the SALTED input file named inp.yaml.

__init__(_dev_inp_fpath=None)

Initialize configuration parser

Parameters:

Name Type Description Default
_dev_inp_fpath str | None

Path to the input file. Defaults to None. Don't use this argument, it's for testing only!!!

 None

check_input(inp)

Check keys (required, optional, not allowed), and value types and ranges

Format: (required, default value, value type, value extra check)

About required
  • True -> required
  • False -> optional, will fill in default value if not found
  • False + PLACEHOLDER -> optional in some cases, but required in others cases
  • (if the default value is $PLACEHOLDER, it means the key is optional for some cases, but required for others)
About PLACEHOLDER
  • If a key is optional in some cases, but required in others, the default value is set to PLACEHOLDER.
  • The extra value checking should consider the PLACEHOLDER value!
About sparsify
  • The config doesn't explicitly require the sparsify section, and ncut is 0 by default (don't sparsify).

get_all_params()

return all parameters with a tuple

About sparsify in the return tuple: - If ncut <=0, sparsify = False. - If ncut > 0, sparsify = True.

Please copy & paste: 

(saltedname, saltedpath, saltedtype,
 filename, species, average,
 path2qm, qmcode, qmbasis, dfbasis,
 filename_pred, predname, predict_data, alpha_only,
 rep1, rcut1, sig1, nrad1, nang1, neighspe1,
 rep2, rcut2, sig2, nrad2, nang2, neighspe2,
 sparsify, nsamples, ncut,
 zeta, Menv, Ntrain, trainfrac, regul, eigcut,
 gradtol, restart, trainsel,
 nspe1, nspe2, HP1, HP2) = ParseConfig().get_all_params()
HP1 and HP2 are the featomic hyperparameter dicts for rep1 and rep2, built from their respective configs via build_featomic_hyper_params().

get_all_params_simple1()

return all parameters with a tuple

Please copy & paste: 

(
    filename, species, average,
    rep1, rcut1, sig1, nrad1, nang1, neighspe1,
    rep2, rcut2, sig2, nrad2, nang2, neighspe2,
    sparsify, nsamples, ncut,
    z, Menv, Ntrain, trainfrac, regul, eigcut,
    gradtol, restart, trainsel
) = ParseConfig().get_all_params_simple1()

get_loader()

Add constructors to the yaml.SafeLoader For details, see: https://pyyaml.org/wiki/PyYAMLDocumentation

parse_input()

Parse input file Procedure: - get loader (for constructors and resolvers) - load yaml

Returns:

Name Type Description
AttrDict AttrDict

Parsed input file