Sampling Bias

Bias term definitions for biased sampling techniques.

Bias terms can be added to an MCKernel in order to generate samples that are biased accordingly.

class FugacityBias(sublattices, fugacity_fractions=None, **kwargs)

Bases: MCBias

Fugacity fraction bias.

This bias corresponds directly to using a composition bias. Using this with a CanonicalEnsemble keeps fugacity fractions constant, which implicitly sets the chemical potentials, albeit for a specific temperature. Since one species per sublattice is the reference species, to calculate actual fugacities, the reference fugacity must be computed as an ensemble average and all other fugacities can then be calculated. From the fugacities and the set temperature, the corresponding chemical potentials can then be calculated.

Initialize fugacity ratio bias.

Parameters:

• sublattices (List[Sublattice]) – list of active sublattices, containing species information and site indices in sublattice.

• fugacity_fractions (sequence of dicts) – optional Dictionary of species name and fugacity fraction for each sublattice (.i.e think of it as the sublattice concentrations for random structure). If not given this will be taken from the prim structure used in the cluster subspace. Needs to be in the same order as the corresponding sublattice.

kwargs:

Keyword arguments for initializing MCUsher.

compute_bias(occupancy)

Compute bias from occupancy.

Parameters:

occupancy (np.ndarray) – Encoded occupancy string.

Returns:

Float, bias value.

compute_bias_change(occupancy, step)

Compute bias change from step.

The returned value needs to be the difference of bias logs, log(bias_f) - log(bias_i), when the bias terms would directly multiply the ensemble probability (i.e. exp(-beta * E) * bias).

Parameters:

• occupancy – (ndarray): encoded occupancy array.

• step – (List[tuple(int,int)]): step returned by MCUsher.

Returns:

float, change of bias value after step.

property fugacity_fractions

Get the fugacity fractions for species on active sublatts.

class MCBias(sublattices, rng=None, *args, **kwargs)

Bases: ABC

Base bias term class.

Note

Any MCBias should be implemented as beta * E - bias will be minimized in thermodynamics kernel.

sublattices

list of sublattices with active sites.

Type:

List[Sublattice]

Initialize MCBias.

Parameters:

• sublattices (List[Sublattice]) – list of active sublattices, containing species information and site indices in sublattice.

• rng (np.Generator) – optional The given PRNG must be the same instance as that used by the kernel and any bias terms, otherwise reproducibility will be compromised.

• args – Additional arguments buffer.

• kwargs – Additional keyword arguments buffer.

abstract compute_bias(occupancy)

Compute bias from occupancy.

Parameters:

occupancy (np.ndarray) – encoded occupancy string.

Returns:

Float, bias value.

compute_bias_change(occupancy, step)

Compute bias change from step.

Parameters:

• occupancy – (ndarray): encoded occupancy array.

• step – (List[tuple(int,int)]): step returned by MCUsher.

Returns:

Float, change of bias value after step.

class SquareChargeBias(sublattices, penalty=0.5, **kwargs)

Bases: MCBias

Square charge bias.

This bias penalizes energy on square of the system net charge.

Square charge bias.

Parameters:

• sublattices (List[Sublattice]) – List of active sublattices, containing species information and site indices in sublattice. Must include all sites!

• penalty (float) – optional Penalty factor. energy/kT will be penalized by adding penalty * charge**2. Must be positive. Default to 0.5, which works for most of the cases.

kwargs:

Keyword arguments for initializing MCUsher.

compute_bias(occupancy)

Compute bias from occupancy.

Parameters:

occupancy (np.ndarray) – Encoded occupancy string.

Returns:

Float, bias value.

class SquareHyperplaneBias(sublattices, hyperplane_normals, hyperplane_intercepts, penalty=0.5, **kwargs)

Bases: MCBias

Square hyperplane bias.

This bias penalizes energy on sum square of distance from a composition n (“counts” format) to hyperplanes A n = b (in the unconstrained composition space, see CompositionSpace document). In other words, this bias penalizes the composition’s deviation from the constraints in A n = b.

Square composition bias.

Use this when you have other constraints to the composition than the charge constraint. :type sublattices: :param sublattices: List of active sublattices, containing species information and

site indices in sublattice. Must include all sites!

Parameters:

• hyperplane_normals (2D ArrayLike) – Normal vectors of hyperplanes, each in a row. (The matrix A.)

• hyperplane_intercepts (1D ArrayLike) – Intercepts of each hyperplane. (The vector b.)

• of (The matrix A and the vector b together forms a set) –

• hyperplanes (constraint) – A n = b. (Per-super-cell, not per-primitive cell).

• penalty (float) – optional Penalty factor. energy/kT will be penalized by adding penalty * ||A n - b||**2. Must be positive. Default to 0.5, which works for most of the cases.

kwargs:

Keyword arguments for initializing MCUsher.

compute_bias(occupancy)

Compute bias from occupancy.

Parameters:

occupancy (np.ndarray) – Encoded occupancy string.

Returns:

Float, bias value.

available_bias_types()

Get a list of available MCMC biases.

Return type:

tuple[str]

Returns:

tuple[str], list of available MCMC biases.

mcbias_factory(bias_type, sublattices, *args, **kwargs)

Get a MCMC bias from string name.

Parameters:

• bias_type (str) – string specifying bias name to instantiate.

• sublattices (List[Sublattice]) – list of active sublattices, containing species information and site indices in sublattice.

• *args – positional args to instantiate a bias term.

• *kwargs – keyword argument to instantiate a bias term.