xcquinox package
Submodules
xcquinox.net module
- class xcquinox.net.GGA_FxNet_s(depth: int, nodes: int, seed: int, lob_lim=1.804)[source]
Bases:
ModuleS: Exchange enhancementt factor for GGA.
The input to the network is the reduced density gradient, s, and the output is the enhancement factor, Fx.
- name: str
- depth: int
- nodes: int
- seed: int
- lob_lim: float
- net: MLP
- lobf: Module
- class xcquinox.net.GGA_FcNet_s(depth: int, nodes: int, seed: int, lob_lim=2.0)[source]
Bases:
ModuleS: Correlation enhancement factor for GGA.
The input to the network is the reduced density gradient, s, and the output is the enhancement factor, Fc.
- name: str
- depth: int
- nodes: int
- seed: int
- lob_lim: float
- net: MLP
- lobf: Module
- class xcquinox.net.GGA_FxNet_G(depth: int, nodes: int, seed: int, lob_lim=1.804)[source]
Bases:
ModuleS: Exchange enhancementt factor for GGA.
It takes rho and grad_rho as input and outputs the exchange enhancement factor, Fx. It transforms the input to the reduced density gradient, s, and then passes it through the network.
- name: str
- depth: int
- nodes: int
- seed: int
- lob_lim: float
- net: MLP
- lobf: Module
- class xcquinox.net.GGA_FcNet_G(depth: int, nodes: int, seed: int, lob_lim=2.0)[source]
Bases:
Module- name: str
- depth: int
- nodes: int
- seed: int
- lob_lim: float
- net: MLP
- lobf: Module
- class xcquinox.net.GGA_FxNet_sigma(depth: int, nodes: int, seed: int, lob_lim=1.804, lower_rho_cutoff=1e-12)[source]
Bases:
ModuleS: Exchange enhancementt factor for GGA.
It takes rho and sigma (grad_rho²) as input and outputs the exchange enhancement factor, Fx. It transforms the input to the reduced density gradient, s, and then passes it through the network.
- name: str
- depth: int
- nodes: int
- seed: int
- lob_lim: float
- lower_rho_cutoff: float
- net: MLP
- lobf: Module
- class xcquinox.net.GGA_FcNet_sigma(depth: int, nodes: int, seed: int, lob_lim=2.0, lower_rho_cutoff=1e-12)[source]
Bases:
ModuleS: Correlation enhancement factor for GGA.
It takes rho and sigma (grad_rho²) as input and outputs the correlation enhancement factor, Fc. It transforms the input to the reduced density gradient, s, and then passes it through the network.
- name: str
- depth: int
- nodes: int
- seed: int
- lob_lim: float
- lower_rho_cutoff: float
- net: MLP
- lobf: Module
- xcquinox.net.save_xcquinox_model(model, path: str = '', fixing: str | None = None, tail_info: str | None = None, loss: list[float] | None = None)[source]
Save our NN model to a file.
- Parameters:
model (eqx.Module.) – The model to save.
path (str, optional.) – The path to save the model to, defaults to .
fixing (Union[str, None], optional.) – A string to append to the model name, defaults to None. Useful to determine the type of fixing used in the model.
tail_info (Union[str, None], optional.) – A string to append to the model name, defaults to None. Useful to determine any additional information about the model.
loss (Union[list[float], None], optional.) – A list of loss values to save, defaults to None. Useful to determine the loss values during training. Will be saved in a separate file.
- xcquinox.net.load_xcquinox_model(path: str)[source]
Load a model from a file.
Note that we must give the path where the model is stored, without the extension. I.e, in path, we should have the files path.eqx and path.json.
- class xcquinox.net.GGA_FxNet_sigma_UNC(depth: int, nodes: int, seed: int, lob_lim=1.804, lower_rho_cutoff=1e-12)[source]
Bases:
Module- depth: int
- nodes: int
- seed: int
- lob_lim: float
- lower_rho_cutoff: float
- net: MLP
- class xcquinox.net.GGA_FcNet_sigma_UNC(depth: int, nodes: int, seed: int, lob_lim=2.0, lower_rho_cutoff=1e-12)[source]
Bases:
Module- depth: int
- nodes: int
- seed: int
- lob_lim: float
- lower_rho_cutoff: float
- net: MLP
- class xcquinox.net.MGGA_FxNet_sigma(depth: int, nodes: int, seed: int, lob_lim=1.174, lower_rho_cutoff=1e-12)[source]
Bases:
Module- depth: int
- nodes: int
- seed: int
- lob_lim: float
- lower_rho_cutoff: float
- net: MLP
- lobf: Module
- name: str
- class xcquinox.net.MGGA_FxNet_sigma_transform(depth: int, nodes: int, seed: int, lob_lim=1.174, lower_rho_cutoff=1e-12)[source]
Bases:
Module- depth: int
- nodes: int
- seed: int
- lob_lim: float
- lower_rho_cutoff: float
- net: MLP
- lobf: Module
- name: str
- class xcquinox.net.MGGA_FcNet_sigma(depth: int, nodes: int, seed: int, lob_lim=1.174, lower_rho_cutoff=1e-12)[source]
Bases:
Module- depth: int
- nodes: int
- seed: int
- lob_lim: float
- lower_rho_cutoff: float
- net: MLP
- lobf: Module
- name: str
- class xcquinox.net.MGGA_FcNet_sigma_transform(depth: int, nodes: int, seed: int, lob_lim=1.174, lower_rho_cutoff=1e-12)[source]
Bases:
Module- depth: int
- nodes: int
- seed: int
- lob_lim: float
- lower_rho_cutoff: float
- net: MLP
- lobf: Module
- name: str
- class xcquinox.net.eX(n_input, n_hidden=16, depth=3, use=[], ueg_limit=False, lob=1.804, seed=92017, spin_scaling=True)[source]
Bases:
Module- ueg_limit: Array
- spin_scaling: bool
- lob: Array
- n_input: int
- seed: int
- depth: int
- use: list
- net: Module
- tanh: named_call
- lobf: Module
- sig: named_call
- shift: Array
- class xcquinox.net.eC(n_input=2, n_hidden=16, depth=3, use=[], ueg_limit=False, lob=2.0, seed=92017, spin_scaling=False)[source]
Bases:
Module- spin_scaling: bool
- ueg_limit: Array
- n_input: int
- seed: int
- depth: int
- use: list
- net: Module
- sig: named_call
- tanh: named_call
- lob: Array
- lobf: Module
- xcquinox.net.make_net(xorc, level, depth, nhidden, ninput=None, use=None, spin_scaling=None, lob=None, ueg_limit=None, random_seed=None, savepath=None, configfile='network.config')[source]
make_net is a utility function designed to easily create new, individual exchange or correlation networks with ease. If no extra arguments are specified, the network will be generated with a default structure that respects the various constraints implemented within xcquinox
- Parameters:
xorc (str) – ‘X’ or ‘C’ – the type of network to generate, exchange or correlation
level (str) – one of [‘GGA’, ‘MGGA’, ‘NONLOCAL’, ‘NL’], indicating the desired rung of Jacob’s Ladder. NONLOCAL = NL
depth (int) – The number of hidden layers in the generated network.
nhidden (int) – The number of nodes in a hidden layer
ninput (int, optional) – The number of inputs the network will expect, defaults to None for automatic selection based on level
use (list of ints, optional) – The indices of the descriptors to evaluate the network on, defaults to None
spin_scaling (bool, optional) – Whether or not to enforce the spin-scaling contraint in the generated network, defaults to None
lob (float, optional) – Lieb-Oxford bound: If non-zero (i.e., truthy), the output values of e_x or e_c will be squashed between [-1, lob-1], defaults to None
ueg_limit (bool, optional) – Whether or not to enforce the UEG scaling constraint, defaults to None
random_seed (int, optional) – The random seed to use in generating initial network weights, defaults to None
savepath (str, optional) – Location to save the generated network and associated config file, defaults to None
configfile (str, optional) – Name for the configuration file, needed when reading in the network to re-generate the same structure, defaults to ‘network.config’
- Returns:
The resulting exchange or correlation network.
- Return type:
- xcquinox.net.eX:
or :xcquinox.net.eC:
- xcquinox.net.get_net(xorc, level, net_path, configfile='network.config', netfile='xc.eqx')[source]
A utility function to easily load in a previously generated network. Functionally creates a random network of the same architecture, then overwrites the weights with those of the saved network.
- Parameters:
xorc (str) – ‘X’ or ‘C’ – the type of network to generate, exchange or correlation
level (str) – one of [‘GGA’, ‘MGGA’, ‘NONLOCAL’, ‘NL’], indicating the desired rung of Jacob’s Ladder. NONLOCAL = NL
net_path (str) – Location of the saved network. Must have a {configfile}.pkl parameter file within.
configfile (str, optional) – Name for the configuration file, needed when reading in the network to re-generate the same structure, defaults to ‘network.config’
netfile (str, optional) – Name for the network file, needed when reading in the network overwrite generated random weights, defaults to ‘xc.eqx’. If Falsy, just generates random network based on config file.
- Returns:
The requested exchange or correlation network.
- Return type:
- xcquinox.net.eX:
or :xcquinox.net.eC:
xcquinox.utils module
- xcquinox.utils.pad_array(arr, max_arr, shape=None, device=CpuDevice(id=0))[source]
Utility function designed to pad an array to a given maximum size, for use during jitted forward passes.
Since JAX jit compilations re-compile everytime a new array shape is passed, padding is a tactic to avoid this memory consumption.
- Parameters:
arr (jax.Array) – The original array meant to be padded
max_arr (jax.Array) – The array whose size is to be emulated, or an empty value if manually specifying shape
shape (tuple of ints, optional) – The array shape you want to pad to, if known a priori, defaults to None
device (jax.Device, optional) – Where to place the padded arrays, defaults to jax.devices(‘cpu’)[0]
- Returns:
Padded version of arr
- Return type:
jax.Array
- xcquinox.utils.pad_array_list(arrlst, device=CpuDevice(id=0))[source]
Automatically finds maximum size from a list of arrays, and pads all arrays to that size
- Parameters:
arrlst (list) – List of jax.Arrays with varying sizes
device (jax.Device, optional) – Where to place the newly padded arrays, defaults to jax.devices(‘cpu’)[0]
- Returns:
List of the padded arrays
- Return type:
list of jax.Array
- xcquinox.utils.ase_atoms_to_mol(atoms, basis='6-311++G(3df,2pd)', charge=0, spin=None)[source]
Converts an ASE.Atoms object into a PySCF(ad).gto.Mol object
- Parameters:
atoms (
ASE.Atoms) – ASE.Atoms object of a single molecule/systembasis (str, optional) – Basis set to assign in PySCF(AD), defaults to ‘6-311++G(3df,2pd)’
charge (int, optional) – Global charge of molecule, defaults to 0
spin (int, optional) – Specify spin if desired. Defaults to None, which has PySCF guess spin based on electron number/occupation. Use with care.
- Returns:
A string of the molecule’s name, and the Mole object for pyscfad to work with.
- Return type:
(str,
pyscfad.gto.Mole)
- xcquinox.utils.get_spin(at)[source]
Returns single-atom, ground-state spin configurations, since pyscf does not guess this correctly.
Relies on xcquinox.utils.spins_dict, a hard-coded dictionary populated with atom names and associated spins.
- Parameters:
at (
ase.Atoms) –ase.Atomsobject, with an associatedase.Atoms.infodictionary optionally containing keys ‘spin’, ‘radical’, or ‘openshell’ and associated integer pair. If specified, returns that value. Otherwise, uses the value in spins_dict for single atoms.- Returns:
The guessed spin value
- Return type:
int
- xcquinox.utils.get_dm_moe(dm, eri, vxc_grad_func, mo_occ, hc, s, ogd, alpha0=0.7)[source]
Generates the DM, molecular orbital energies, and molecular orbital coefficients for a model
_extended_summary_
- Parameters:
dm (jax.Array) – The initial DM starting point for the calculation.
eri (jax.Array) – The electron repulsion integrals to use in generating the effective potential
vxc_grad_func (function) – A function F(dm) = E, with which the derivative is taken to generate Vxc
mo_occ (jax.Array) – The molecular orbital occupation numbers for the molecule
hc (jax.Array) – The molecule’s core Hamiltonian
s (jax.Array) – The molecule’s overlap matrix
ogd (tuple/jax.Array) – The molecule’s original DM dimensions
alpha0 (float, optional) – The mixing parameter used for the one-shot DM creation, defaults to 0.7
- Returns:
tuple of (density matrix, molecular orbital energies, molecular orbital coefficients)
- Return type:
tuple of jax.Array
- xcquinox.utils.gen_grid_s(npts=30000, start_stop_rho=(0.01, 5), start_stop_s=(0.01, 5), train_pct=0.8, ranseed=92017, sigma=False)[source]
Generates a grid of rho, grad_rho, and reduced_density_gradient values. Will generate ~sqrt(npts) sized rho and s arrays, used to generate a grad_rho array.
The indices of these arrays are then randomly sub-sampled to yield (1 - train_pct) percent of validation indices, which are excluded from the training meshgrid.
- Parameters:
npts (int, optional) – Number of points to generate in each array, defaults to 30000. The function will get close, but not necessarily exactly the number of points, unless the desired value is a perfect square.
start_stop_rho (tuple, optional) – Bounds for the generated reduced_density_gradient values, defaults to (0.01, 5)
start_stop_s (tuple, optional) – Bounds for the generated rho values, defaults to (0.01, 5)
train_pct (float, optional) – Percentage of generated BASE values to use in training, defaults to 0.8
ranseed (int, optional) – Seed to set for training/validation index selection, defaults to 92017
sigma (bool, optional) – If flagged, will return array of SIGMA (= grad_rho**2) values instead of “grad_rho” values, defaults to False
- Returns:
List of [(train_inds, val_inds), (rho_values, grad_rho_values, s_values), (trho_flat, tgrad_rho_flat, ts_flat), (vrho_flat, vgrad_rho_flat, vs_flat)]
- Return type:
list
- xcquinox.utils.PBE_Fx(rho, grad_rho, lower_rho_cutoff=1e-12)[source]
Given density and density gradient magnitude values, calculates the PBE Exchange Enhancement Factor as denoted in:
Equation 14 from PBE paper – DOI: 10.1103/PhysRevLett.77.3865
- Parameters:
rho (float, broadcastable array) – the density value on the grid
grad_rho (float, broadcastable array) – the magnitude of the density gradient values on the grid
lower_rho_cutoff (float, optional) – a cut-off to bypass potential division by zero in the division by rho, defaults to 1e-12
- Returns:
The numerical value(s) of the exchange enhancement factor
- Return type:
float, broadcastable array
- xcquinox.utils.PBE_Fc(rho, grad_rho, lower_rho_cutoff=1e-12)[source]
Given density and density gradient magnitude values, calculates the PBE Correlation Enhancement Factor as denoted in:
CRITICALLY, this function is only valid for the non-spin-polarized case where zeta = 0
Equation 3 from PBE paper – DOI: 10.1103/PhysRevLett.77.3865
- Parameters:
rho (float, broadcastable array) – the density value on the grid
grad_rho (float, broadcastable array) – the magnitude of the density gradient values on the grid
lower_rho_cutoff (float, optional) – a cut-off to bypass potential division by zero in the division by rho, defaults to 1e-12
- Returns:
The numerical value(s) of the correlation enhancement factor
- Return type:
float, broadcastable array
- xcquinox.utils.pw91_correlation_energy_density(rho)[source]
Calculate the correlation energy density according to the PW91 functional.
Parameters: - rho: electron density (numpy array or scalar) - grad_rho: gradient of the electron density (numpy array or scalar)
Returns: - correlation energy density (numpy array or scalar)
- xcquinox.utils.lda_x(rho)[source]
The HEG exchange energy density.
- Parameters:
rho (jax.numpy array) – Total electron density array on a grid.
- Returns:
Exchange energy density array.
- Return type:
jax.numpy array
- xcquinox.utils.pw92c(rho)[source]
Implements the Perdew-Wang ‘92 local correlation (beyond RPA) for the unpolarized case. Reference: J.P.Perdew & Y.Wang, PRB, 45, 13244 (1992)
- Parameters:
rho (jax.numpy array) – Total electron density array on a grid.
- Returns:
Correlation energy density and potential arrays.
- Return type:
tuple of (jax.numpy array, jax.numpy array)
- xcquinox.utils.pw92c_unpolarized(rho)[source]
Implements the Perdew-Wang ‘92 local correlation (beyond RPA) for the unpolarized case. Reference: J.P.Perdew & Y.Wang, PRB, 45, 13244 (1992)
- Parameters:
rho (jax.numpy array) – Total electron density array on a grid.
- Returns:
Correlation energy density array.
- Return type:
jax.numpy array
xcquinox.xc module
- class xcquinox.xc.eXC(grid_models=[], heg_mult=True, pw_mult=True, level=1, exx_a=None, epsilon=1e-06, debug=False, nlstart_i=3, nlend_i=12, verbose=False)[source]
Bases:
Module- heg_mult: bool
- pw_mult: bool
- level: int
- grid_models: list
- epsilon: Array
- loge: Array
- s_gam: Array
- debug: bool
- nlstart_i: int
- nlend_i: int
- verbose: bool
- heg_model: Module
- pw_model: Module
- model_mult: list
- exx_a: Array
- vprint(str)[source]
Prints if verbose tag is set on the object
- Parameters:
str (str) – The string to be printed
- l_1(rho)[source]
l_1 Level 1 (LDA-level) Descriptor – Creates dimensionless quantity from rho.
Equation 3 from the base paper.
\[x_0 = \rho^{1/3}\]- Parameters:
rho (jax.Array) – density
- Returns:
Scaled density
- Return type:
jax.Array
- l_2(rho, gamma)[source]
l_2 Level 2 (GGA-level) Descriptor – Reduced gradient density
Equation 5 from the base paper.
\[x_2=s=\frac{1}{2(3\pi^2)^{1/3}} \frac{|\nabla \rho|}{\rho^{4/3}}\]- Parameters:
rho (jax.Array) – density
gamma (jax.Array) – squared density gradient
- Returns:
reduced density gradient s
- Return type:
jax.Array
- l_3(rho, gamma, tau)[source]
l_3 Level 3 (MGGA-level) Descriptor – Reduced kinetic energy density
Equation 6 from the base paper.
\[\tau^W = \frac{|\nabla \rho|^2}{8\rho}, \tau^{unif} = \frac{3}{10} (3\pi^2)^{2/3}\rho^{5/3}.\]- Parameters:
rho (jax.Array) – density
gamma (jax.Array) – squared density gradient
tau (jax.Array) – kinetic energy density
- Returns:
reduced kinetic energy density
- Return type:
jax.Array
- l_4(rho, nl)[source]
l_4 Level 4 (Non-local level) Descriptor – Unitless electrostatic potential
- Parameters:
rho (jax.Array) – density
nl (jax.Array) – non-local values arising from density contractions
- Returns:
the non-local descriptors
- Return type:
jax.Array
- nl_4(mf, dm, ao=None, gw=None, coor=None)[source]
Level 4 (non-local level) descriptor generator – generates the CIDER nonlocal descriptors, given a density matrix and a converged kernel with associated mol and grids
Optional parameters not provided will use the values already associated with mf.grids; provide custom values for things like grid subsets.
- Parameters:
mf (pyscf(ad).dft.RKS kernel) – The converged calculation kernel, passed to RKSAnalyzer for descriptor generation
dm (jax.Array) – Density matrix to use in nonlocal desciptor generation
ao (jax.Array) – Atomic orbital values to use in nonlocal desciptor generation, defaults to None
gw (jax.Array) – Grid weights to use in nonlocal desciptor generation, defaults to None
coor (jax.Array) – Grid coordinates to use in nonlocal desciptor generation, defaults to None
- Returns:
The non-local CIDER descriptors, from self.nlstart_i to self.nlend_i
- Return type:
jax.Array
- get_descriptors(rho0_a, rho0_b, gamma_a, gamma_b, gamma_ab, tau_a, tau_b, spin_scaling=False, mf=None, dm=None, ao=None, gw=None, coor=None)[source]
get_descriptors Creates ‘ML-compatible’ descriptors from the electron density and its gradients, a & b correspond to spin channels
- Parameters:
rho0_a (jax.Array) – \(\rho\) in spin-channel a
rho0_b (jax.Array) – \(\rho\) in spin-channel b
gamma_a (jax.Array) – \(|\nabla \rho|^2\) in spin-channel b
gamma_b (jax.Array) – \(|\nabla \rho|^2\) in spin-channel b
gamma_ab (jax.Array) – \(|\nabla \rho|^2\), contracted from both spin channels
tau_a (jax.Array) – KE density in spin-channel a
tau_b (jax.Array) – KE density in spin-channel b
spin_scaling (bool, optional) – Flag for spin-scaling, defaults to False
mf (pyscf(ad).dft.RKS kernel) – The converged calculation kernel, passed to RKSAnalyzer for descriptor generation if self.level > 3, defaults to None
dm (jax.Array) – Density matrix to use in nonlocal desciptor generation if self.level > 3, defaults to None
ao (jax.Array) – Atomic orbital values to use in nonlocal desciptor generation if self.level > 3, defaults to None
gw (jax.Array) – Grid weights to use in nonlocal desciptor generation if self.level > 3, defaults to None
coor (jax.Array) – Grid coordinates to use in nonlocal desciptor generation if self.level > 3, defaults to None
- Returns:
Array of the machine-learning descriptors on the grid
- Return type:
jax.Array
- eval_grid_models(rho, mf=None, dm=None, ao=None, gw=None, coor=None)[source]
eval_grid_models Evaluates all models stored in self.grid_models along with HEG exchange and correlation
- Parameters:
rho (jax.Array) – List/array with [rho0_a,rho0_b,gamma_a,gamma_ab,gamma_b, dummy for laplacian, dummy for laplacian, tau_a, tau_b, non_loc_a, non_loc_b] Shape assumes, for instance, that rho0_a = rho[:, 0], etc.
mf (pyscf(ad).dft.RKS kernel) – The converged calculation kernel, passed to RKSAnalyzer for nonlocal descriptor generation
dm (jax.Array) – Density matrix to use in nonlocal desciptor generation
ao (jax.Array) – Atomic orbitals to use in non-local descriptor generation, defaults to None
gw (jax.Array) – Grid weights to use in non-local descr generation, defaults to None
coor (jax.Array) – Grid coordinates to use in non-local descr generation, defaults to None
- Returns:
The exchange-correlation energy density (on the grid)
- Return type:
jax.Array
- xcquinox.xc.make_xcfunc(level, x_net_path, c_net_path, configfile='network.config', xdsfile='xc.eqx', cdsfile='xc.eqx', savepath=None)[source]
Constructs the combined :xcquinox.xc.eXC: object from previously-created and separate :xcquinox.net.eX: and :xquinox.net.eC: objects
- Parameters:
level (str) – one of [‘GGA’, ‘MGGA’, ‘NONLOCAL’, ‘NL’], indicating the desired rung of Jacob’s Ladder. NONLOCAL = NL
x_net_path (str) – Location of the saved exchange network. Must have a {configfile}.pkl parameter file within.
c_net_path (str) – Location of the saved correlation network. Must have a {configfile}.pkl parameter file within.
configfile (str, optional) – Name for the configuration file, needed when reading in the network to re-generate the same structure, defaults to ‘network.config’
xdsfile (str, optional) – Name for the exchange network file, needed when reading in the network overwrite generated random weights, defaults to ‘xc.eqx’
cdsfile (str, optional) – Name for the correlation network file, needed when reading in the network overwrite generated random weights, defaults to ‘xc.eqx’
savepath (str, optional) – Location to save the generated network and associated config file, defaults to None
- Returns:
The resulting exchange-correlation functional.
- Return type:
- xcquinox.xc.eXC:
- xcquinox.xc.get_xcfunc(level, xc_net_path, configfile='network.config', xcdsfile='xc.eqx')[source]
Retrieves an XC functional object based on configuration files in given directory.
- Parameters:
level (str) – one of [‘GGA’, ‘MGGA’, ‘NONLOCAL’, ‘NL’], indicating the desired rung of Jacob’s Ladder. NONLOCAL = NL
xc_net_path (str) – Location of the saved functional. Must have BOTH a ‘x’+{configfile}+’.pkl’ and ‘c’+{configfile}+’.pkl’ parameter files within.
configfile (str, optional) – Base name for the configuration files to be read in, defaults to ‘network.config’
xcdsfile (str, optional) – If present, the network weights will be overwritten by what’s present in this file, defaults to ‘xc.eqx’
- Returns:
The loaded functional
- Return type:
- xcquinox.xc.eXC:
Module contents
A machine learning framework using the equinox library for learning XC functionals with JAX.