espei package

Submodules

espei.analysis module

Tools for analyzing ESPEI runs

espei.analysis.truncate_arrays(trace_array, prob_array=None)

Return slides of ESPEI output arrays with any empty remaining iterations (zeros) removed.

Parameters:
  • trace_array (np.ndarray) – Array of the trace from an ESPEI run. Should have shape (chains, iterations, parameters)
  • prob_array (np.ndarray) – Array of the lnprob output from an ESPEI run. Should have shape (chains, iterations)
Returns:

A slide of the zeros-removed trace array is returned if only the trace is passed. Otherwise a tuple of both the trace and lnprob are returned.

Return type:

np.ndarry or (np.ndarray, np.ndarray)

espei.core_utils module

Internal utilities for developer use. May not be useful to users.

espei.core_utils.get_data(comps, phase_name, configuration, symmetry, datasets, prop)

Return list of cleaned single phase datasets matching the passed arguments.

Parameters:
  • comps (list) – List of string component names
  • phase_name (str) – Name of phase
  • configuration (tuple) – Sublattice configuration as a tuple, e.g. (“CU”, (“CU”, “MG”))
  • symmetry (list of lists) – List of sublattice indices with symmetry
  • datasets (espei.utils.PickleableTinyDB) – Database of datasets to search for data
  • prop (list) – String name of the property of interest.
Returns:

List of datasets matching the arguments.

Return type:

list

espei.core_utils.get_prop_data(comps, phase_name, prop, datasets)

Return datasets that match the components, phase and property

Parameters:
  • comps (list) – List of components to get data for
  • phase_name (str) – Name of the phase to get data for
  • prop (str) – Property to get data for
  • datasets (espei.utils.PickleableTinyDB) – Datasets to search for data
Returns:

List of dictionary datasets that match the criteria

Return type:

list

espei.core_utils.get_samples(desired_data)

Return the data values from desired_data, transformed to interaction products.

Parameters:desired_data (list) – List of matched desired data, e.g. for a single property
Returns:List of sample values that are properly transformed.
Return type:list

Notes

Transforms data to interaction products, e.g. YS*{}^{xs}G=YS*XS*DXS^{n} {}^{n}L

espei.core_utils.ravel_conditions(values, *conditions, **kwargs)

Broadcast and flatten conditions to the shape dictated by the values.

Special handling for ZPF data that does not have nice array values.

Parameters:
  • values (list) – Multidimensional lists of values
  • conditions (list) – List of conditions to broadcast. Must be the same length as the number of dimensions of the values array. In code, the following must be True: all([s == len(cond) for s, cond in zip(values.shape, conditions)])
  • zpf (bool, optional) – Whether to consider values as a special case of ZPF data (not an even grid of conditions) Default is False
Returns:

Tuple of ravelled conditions

Return type:

tuple

Notes

The current implementation of ZPF data only has the shape for one condition and this assumption is hardcoded in various places.

Here we try to be as general as possible by explicitly calculating the shape of the ZPF values.

A complication of this is that the user of this function must pass the correct conditions because usually T and P are specified in ZPF (but, again, only one can actually be a condition given the current shape).

espei.core_utils.ravel_zpf_values(desired_data, independent_comps, conditions=None)

Unpack the phases and compositions from ZPF data. Dependent components are converted to independent components.

Parameters:
  • desired_data (espei.utils.PickleableTinyDB) – The selected data
  • independent_comps (list) – List of indepdendent components. Used for mass balance component conversion
  • conditions (dict) – Conditions to filter for. Right now only considers fixed temperatures
Returns:

A dictonary of list of lists of tuples. Each dictionary key is the number of phases in equilibrium, e.g. a key “2” might have values [[(PHASE_NAME_1, {‘C1’: X1, ‘C2’: X2}, refkey), (PHASE_NAME_2, {‘C1’: X1, ‘C2’: X2}, refkey)], …] Three would have three inner tuples and so on.

Return type:

dict

espei.core_utils.recursive_map(f, x)

map, but over nested lists

Parameters:
  • f (callable) – Function to apply to x
  • x (list or value) – Value passed to v
Returns:

Return type:

list or value

espei.core_utils.symmetry_filter(x, config, symmetry)

Return True if the candidate sublattice configuration has any symmetry which matches the phase model symmetry.

Parameters:
  • x (dict) – the candidate dataset ‘solver’ dict. Must contain the “sublattice_configurations” key
  • config (list) – the configuration of interest: e.g. [‘AL’, [‘AL’, ‘NI’], ‘VA’]
  • symmetry (list) – tuple of tuples where each inner tuple is a group of equivalent sublattices. A value of ((0, 1), (2, 3, 4)) means that sublattices at indices 0 and 1 are symmetrically equivalent to each other and sublattices at indices 2, 3, and 4 are symetrically equivalent to each other.
Returns:

Return type:

bool

espei.datasets module

exception espei.datasets.DatasetError

Bases: Exception

Exception raised when datasets are invalid.

espei.datasets.check_dataset(dataset)

Ensure that the dataset is valid and consistent.

Currently supports the following validation checks: * data shape is valid * phases and components used match phases and components entered * individual shapes of keys, such as ZPF, sublattice configs and site ratios

Planned validation checks: * all required keys are present

Note that this follows some of the implicit assumptions in ESPEI at the time of writing, such that conditions are only P, T, configs for single phase and essentially only T for ZPF data.

Parameters:dataset (dict) – Dictionary of the standard ESPEI dataset.
Returns:
Return type:None
Raises:DatasetError – If an error is found in the dataset
espei.datasets.clean_dataset(dataset)

Clean an ESPEI dataset dictionary.

Parameters:dataset (dict) – Dictionary of the standard ESPEI dataset. dataset : dic
Returns:Modified dataset that has been cleaned
Return type:dict

Notes

Assumes a valid, checked dataset. Currently handles * Converting expected numeric values to floats

espei.datasets.load_datasets(dataset_filenames)

Create a PickelableTinyDB with the data from a list of filenames.

Parameters:dataset_filenames ([str]) – List of filenames to load as datasets
Returns:
Return type:PickleableTinyDB
espei.datasets.recursive_glob(start, pattern)

Recursively glob for the given pattern from the start directory.

Parameters:
  • start (str) – Path of the directory to walk while for file globbing
  • pattern (str) – Filename pattern to match in the glob
Returns:

List of matched filenames

Return type:

[str]

espei.espei_script module

Automated fitting script.

A minimal run must specify an input.json and a datasets folder containing input files.

espei.espei_script.get_dask_config_paths()
espei.espei_script.get_run_settings(input_dict)

Validate settings from a dict of possible input.

Performs the following actions: 1. Normalize (apply defaults) 2. Validate against the schema

Parameters:input_dict (dict) – Dictionary of input settings
Returns:Validated run settings
Return type:dict
Raises:ValueError
espei.espei_script.log_version_info()

Print version info to the log

espei.espei_script.main()

Handle starting ESPEI from the command line. Parse command line arguments and input file.

espei.espei_script.run_espei(run_settings)

Wrapper around the ESPEI fitting procedure, taking only a settings dictionary.

Parameters:run_settings (dict) – Dictionary of input settings
Returns:
Return type:Either a Database (for generate parameters only) or a tuple of (Database, sampler)

espei.mcmc module

Module for running MCMC in ESPEI

MCMC uses an EnsembleSampler based on Goodman and Weare, Ensemble Samplers with Affine Invariance. Commun. Appl. Math. Comput. Sci. 5, 65-80 (2010).

espei.mcmc.generate_parameter_distribution(parameters, num_samples, std_deviation, deterministic=True)

Return an array of num_samples from a Gaussian distribution about each parameter.

Parameters:
  • parameters (ndarray) – 1D array of initial parameters that will be the mean of the distribution.
  • num_samples (int) – Number of chains to initialize.
  • std_deviation (float) – Fractional standard deviation of the parameters to use for initialization.
  • deterministic (bool) – True if the parameters should be generated deterministically.
Returns:

Return type:

ndarray

espei.mcmc.lnlikelihood(params, comps=None, dbf=None, phases=None, datasets=None, symbols_to_fit=None, phase_models=None, weight_dict=None, callables=None, thermochemical_callables=None)

Calculate the likelihood, $$ ln p( heta|y) $$

espei.mcmc.lnprior(params, priors)

Calculate the log prior given the parameters and prior distributions

Parameters:
  • params (array_like) – Array of parameters to fit.
  • priors (list of scipy.stats.rv_continuous-like) – List of priors for each parameter in that obey the rv_contnuous type interface. Specifically, each element in the list must have a logpdf method. Must correspond (same shape and order) to params.
Returns:

Return type:

float

espei.mcmc.lnprob(params, prior_rvs=None, dbf=None, comps=None, phases=None, datasets=None, symbols_to_fit=None, phase_models=None, scheduler=None, weight_dict=None, callables=None, thermochemical_callables=None)

Returns the log probability of a set of parameters

$$ ln p(y| heta) propto ln p( heta) + ln p( heta|y) $$

Parameters:
  • params (array_like) – Array of parameters to fit.
  • prior_rvs (list of scipy.stats.rv_continuous-like) – List of priors for each parameter in that obey the rv_contnuous type interface. Specifically, each element in the list must have a logpdf method. Must correspond (same shape and order) to params.
  • dbf (pycalphad.Database) – Database to consider
  • comps (list) – List of active component names
  • phases (list) – List of phases to consider
  • datasets (espei.utils.PickleableTinyDB) – Datasets that contain single phase data
  • phase_models (dict) – Phase models to pass to pycalphad calculations
  • callables (dict) – Callables to pass to pycalphad
  • symbols_to_fit (list) – List of names of parameter symbols to replace. Must correspond (same shape and order) to params.
  • phase_models – Dictionary of {phase name: Model instance}
  • scheduler (None) – Deprecated.
  • callables – Dictionary of {phase name: {phase callables dict}}
  • thermochemical_callables – Dictionary of {output property: {phase name: {phase callables dict}}}. These callables must have ideal mixing portions removed.
  • weight_dict (dict) – Dictionary of weights for each data type, e.g. {‘ZPF’: 20, ‘HM’: 2}
Returns:

Return type:

float

espei.mcmc.mcmc_fit(dbf, datasets, iterations=1000, save_interval=100, chains_per_parameter=2, chain_std_deviation=0.1, scheduler=None, tracefile=None, probfile=None, restart_trace=None, deterministic=True, prior=None, mcmc_data_weights=None)

Run Markov Chain Monte Carlo on the Database given datasets

Parameters:
  • dbf (Database) – A pycalphad Database to fit with symbols to fit prefixed with VV followed by a number, e.g. VV0001
  • datasets (PickleableTinyDB) – A database of single- and multi-phase to fit
  • iterations (int) – Number of trace iterations to calculate in MCMC. Default is 1000 iterations.
  • save_interval (int) – interval of iterations to save the tracefile and probfile
  • chains_per_parameter (int) – number of chains for each parameter. Must be an even integer greater or equal to 2. Defaults to 2.
  • chain_std_deviation (float) – standard deviation of normal for parameter initialization as a fraction of each parameter. Must be greater than 0. Default is 0.1, which is 10%.
  • scheduler (callable) – Scheduler to use with emcee. Must implement a map method.
  • tracefile (str) – filename to store the trace with NumPy.save. Array has shape (chains, iterations, parameters)
  • probfile (str) – filename to store the log probability with NumPy.save. Has shape (chains, iterations)
  • restart_trace (np.ndarray) – ndarray of the previous trace. Should have shape (chains, iterations, parameters)
  • deterministic (bool) – If True, the emcee sampler will be seeded to give deterministic sampling draws. This will ensure that the runs with the exact same database, chains_per_parameter, and chain_std_deviation (or restart_trace) will produce exactly the same results.
  • prior (str) – Prior to use to generate priors. Defaults to ‘zero’, which keeps backwards compatibility. Can currently choose ‘normal’, ‘uniform’, ‘triangular’, or ‘zero’.
  • mcmc_data_weights (dict) – Dictionary of weights for each data type, e.g. {‘ZPF’: 20, ‘HM’: 2}
Returns:

  • dbf (Database) – Resulting pycalphad database of optimized parameters
  • sampler (EnsembleSampler, ndarray)) – emcee sampler for further data wrangling

espei.paramselect module

The paramselect module handles automated parameter selection for linear models.

Automated Parameter Selection End-members

Note: All magnetic parameters from literature for now. Note: No fitting below 298 K (so neglect third law issues for now).

For each step, add one parameter at a time and compute AICc with max likelihood.

Cp - TlnT, T**2, T**-1, T**3 - 4 candidate models (S and H only have one required parameter each. Will fit in full MCMC procedure)

Choose parameter set with best AICc score.

espei.paramselect.fit_formation_energy(dbf, comps, phase_name, configuration, symmetry, datasets, ridge_alpha=1e-100, features=None)

Find suitable linear model parameters for the given phase. We do this by successively fitting heat capacities, entropies and enthalpies of formation, and selecting against criteria to prevent overfitting. The “best” set of parameters minimizes the error without overfitting.

Parameters:
  • dbf (Database) – pycalphad Database. Partially complete, so we know what degrees of freedom to fix.
  • comps ([str]) – Names of the relevant components.
  • phase_name (str) – Name of the desired phase for which the parameters will be found.
  • configuration (ndarray) – Configuration of the sublattices for the fitting procedure.
  • symmetry ([[int]]) – Symmetry of the sublattice configuration.
  • datasets (PickleableTinyDB) – All the datasets desired to fit to.
  • ridge_alpha (float) – Value of the $alpha$ hyperparameter used in ridge regression. Defaults to 1.0e-100, which should be degenerate with ordinary least squares regression. For now, the parameter is applied to all features.
  • features (dict) – Maps “property” to a list of features for the linear model. These will be transformed from “GM” coefficients e.g., {“CPM_FORM”: (v.T*sympy.log(v.T), v.T**2, v.T**-1, v.T**3)} (Default value = None)
Returns:

{feature: estimated_value}

Return type:

dict

espei.paramselect.fit_ternary_interactions(dbf, phase_name, symmetry, endmembers, datasets, ridge_alpha=0.0)

Fit ternary interactions for a database in place

Parameters:
  • dbf (Database) – pycalphad Database to add parameters to
  • phase_name (str) – Name of the phase to fit
  • symmetry (list) – List of symmetric sublattices, e.g. [[0, 1, 2], [3, 4]]
  • endmembers (list) – List of endmember tuples, e.g. [(‘CU’, ‘MG’)]
  • datasets (PickleableTinyDB) – TinyDB database of datasets
  • ridge_alpha (float) – Value of the $alpha$ hyperparameter used in ridge regression. Defaults to 1.0e-100, which should be degenerate with ordinary least squares regression. For now, the parameter is applied to all features.
Returns:

Modified the Database in place

Return type:

None

espei.paramselect.generate_parameters(phase_models, datasets, ref_state, excess_model, ridge_alpha=1e-100)

Generate parameters from given phase models and datasets

Parameters:
  • phase_models (dict) – Dictionary of components and phases to fit.
  • datasets (PickleableTinyDB) – database of single- and multi-phase to fit.
  • ref_state (str) – String of the reference data to use, e.g. ‘SGTE91’ or ‘SR2016’
  • excess_model (str) – String of the type of excess model to fit to, e.g. ‘linear’
  • ridge_alpha (float) – Value of the $alpha$ hyperparameter used in ridge regression. Defaults to 1.0e-100, which should be degenerate with ordinary least squares regression. For now, the parameter is applied to all features.
Returns:

Return type:

pycalphad.Database

espei.paramselect.get_next_symbol(dbf)

Return a string name of the next free symbol to set

Parameters:dbf (Database) – pycalphad Database. Must have the varcounter attribute set to an integer.
Returns:
Return type:str
espei.paramselect.phase_fit(dbf, phase_name, symmetry, subl_model, site_ratios, datasets, refdata, ridge_alpha, aliases=None)

Generate an initial CALPHAD model for a given phase and sublattice model.

Parameters:
  • dbf (Database) – pycalphad Database to add parameters to.
  • phase_name (str) – Name of the phase.
  • symmetry ([[int]]) – Sublattice model symmetry.
  • subl_model ([[str]]) – Sublattice model for the phase of interest.
  • site_ratios ([float]) – Number of sites in each sublattice, normalized to one atom.
  • datasets (PickleableTinyDB) – All datasets to consider for the calculation.
  • refdata (dict) – Maps tuple(element, phase_name) -> SymPy object defining energy relative to SER
  • ridge_alpha (float) – Value of the $alpha$ hyperparameter used in ridge regression. Defaults to 1.0e-100, which should be degenerate with ordinary least squares regression. For now, the parameter is applied to all features.
  • aliases ([str]) – Alternative phase names. Useful for matching against reference data or other datasets. (Default value = None)
Returns:

Modifies the dbf.

Return type:

None

espei.plot module

Plotting of input data and calculated database quantities

espei.plot.dataplot(comps, phases, conds, datasets, ax=None, plot_kwargs=None, tieline_plot_kwargs=None)

Plot datapoints corresponding to the components, phases, and conditions.

Parameters:
  • comps (list) – Names of components to consider in the calculation.
  • phases ([]) – Names of phases to consider in the calculation.
  • conds (dict) – Maps StateVariables to values and/or iterables of values.
  • datasets (PickleableTinyDB) –
  • ax (matplotlib.Axes) – Default axes used if not specified.
  • plot_kwargs (dict) – Additional keyword arguments to pass to the matplotlib plot function for points
  • tieline_plot_kwargs (dict) – Additional keyword arguments to pass to the matplotlib plot function for tielines
Returns:

A plot of phase equilibria points as a figure

Return type:

matplotlib.Axes

Examples

>>> from espei.datasets import load_datasets, recursive_glob  # doctest: +SKIP
>>> from espei.plot import dataplot  # doctest: +SKIP
>>> datasets = load_datasets(recursive_glob('.', '*.json'))  # doctest: +SKIP
>>> my_phases = ['BCC_A2', 'CUMG2', 'FCC_A1', 'LAVES_C15', 'LIQUID']  # doctest: +SKIP
>>> my_components = ['CU', 'MG' 'VA']  # doctest: +SKIP
>>> conditions = {v.P: 101325, v.T: (500, 1000, 10), v.X('MG'): (0, 1, 0.01)}  # doctest: +SKIP
>>> dataplot(my_components, my_phases, conditions, datasets)  # doctest: +SKIP
espei.plot.eqdataplot(eq, datasets, ax=None, plot_kwargs=None)

Plot datapoints corresponding to the components and phases in the eq Dataset. A convenience function for dataplot.

Parameters:
  • eq (xarray.Dataset) – Result of equilibrium calculation.
  • datasets (PickleableTinyDB) – Database of phase equilibria datasets
  • ax (matplotlib.Axes) – Default axes used if not specified.
  • plot_kwargs (dict) – Keyword arguments to pass to dataplot
Returns:

Return type:

A plot of phase equilibria points as a figure

Examples

>>> from pycalphad import equilibrium, Database, variables as v  # doctest: +SKIP
>>> from pycalphad.plot.eqplot import eqplot  # doctest: +SKIP
>>> from espei.datasets import load_datasets, recursive_glob  # doctest: +SKIP
>>> datasets = load_datasets(recursive_glob('.', '*.json'))  # doctest: +SKIP
>>> dbf = Database('my_databases.tdb')  # doctest: +SKIP
>>> my_phases = list(dbf.phases.keys())  # doctest: +SKIP
>>> eq = equilibrium(dbf, ['CU', 'MG', 'VA'], my_phases, {v.P: 101325, v.T: (500, 1000, 10), v.X('MG'): (0, 1, 0.01)})  # doctest: +SKIP
>>> ax = eqplot(eq)  # doctest: +SKIP
>>> ax = eqdataplot(eq, datasets, ax=ax)  # doctest: +SKIP
espei.plot.multiplot(dbf, comps, phases, conds, datasets, eq_kwargs=None, plot_kwargs=None, data_kwargs=None)

Plot a phase diagram with datapoints described by datasets. This is a wrapper around pycalphad.equilibrium, pycalphad’s eqplot, and dataplot.

Parameters:
  • dbf (Database) – pycalphad thermodynamic database containing the relevant parameters.
  • comps (list) – Names of components to consider in the calculation.
  • phases (list) – Names of phases to consider in the calculation.
  • conds (dict) – Maps StateVariables to values and/or iterables of values.
  • datasets (PickleableTinyDB) – Database of phase equilibria datasets
  • eq_kwargs (dict) – Keyword arguments passed to pycalphad equilibrium()
  • plot_kwargs (dict) – Keyword arguments passed to pycalphad eqplot()
  • data_kwargs (dict) – Keyword arguments passed to dataplot()
Returns:

Return type:

A phase diagram with phase equilibria data as a figure

Examples

>>> from pycalphad import Database, variables as v  # doctest: +SKIP
>>> from pycalphad.plot.eqplot import eqplot  # doctest: +SKIP
>>> from espei.datasets import load_datasets, recursive_glob  # doctest: +SKIP
>>> datasets = load_datasets(recursive_glob('.', '*.json'))  # doctest: +SKIP
>>> dbf = Database('my_databases.tdb')  # doctest: +SKIP
>>> my_phases = list(dbf.phases.keys())  # doctest: +SKIP
>>> multiplot(dbf, ['CU', 'MG', 'VA'], my_phases, {v.P: 101325, v.T: 1000, v.X('MG'): (0, 1, 0.01)}, datasets)  # doctest: +SKIP
espei.plot.plot_parameters(dbf, comps, phase_name, configuration, symmetry, datasets=None, fig=None, require_data=True)

Plot parameters of interest compared with data in subplots of a single figure

Parameters:
  • dbf (Database) – pycalphad thermodynamic database containing the relevant parameters.
  • comps (list) – Names of components to consider in the calculation.
  • phase_name (str) – Name of the considered phase phase
  • configuration (tuple) – Sublattice configuration to plot, such as (‘CU’, ‘CU’) or ((‘CU’, ‘MG’), ‘CU’)
  • symmetry (list) – List of lists containing indices of symmetric sublattices e.g. [[0, 1], [2, 3]]
  • datasets (PickleableTinyDB) – ESPEI datasets to compare against. If None, nothing is plotted.
  • fig (matplotlib.Figure) – Figure to create with axes as subplots.
  • require_data (bool) – If True, plot parameters that have data corresponding data. Defaults to True. Will raise an error for non-interaction configurations.
Returns:

Return type:

None

Examples

>>> # plot the LAVES_C15 (Cu)(Mg) endmember
>>> plot_parameters(dbf, ['CU', 'MG'], 'LAVES_C15', ('CU', 'MG'), symmetry=None, datasets=datasets)  # doctest: +SKIP
>>> # plot the mixing interaction in the first sublattice
>>> plot_parameters(dbf, ['CU', 'MG'], 'LAVES_C15', (('CU', 'MG'), 'MG'), symmetry=None, datasets=datasets)  # doctest: +SKIP

espei.priors module

Classes and functions for retrieving statistical priors for given parameters.

class espei.priors.DistributionParameter(parameter, param_type='absolute')

Bases: object

Handle generating absolute, scaling, shifting parameters.

Examples

>>> dp = DistributionParameter(5.0, 'absolute')  # always get back 5
>>> dp.value(1.0) == 5.0
True
>>> dp = DistributionParameter(-2.0, 'relative')  # multiply by -2
>>> dp.value(2.0) == -4.0
True
>>> dp = DistributionParameter(-1.0, 'shift_absolute')  # subtract 1
>>> dp.value(2.0) == 1.0
True
>>> dp = DistributionParameter(-0.5, 'shift_relative')  # subtract 1/2 value
>>> dp.value(2.0) == 1.0
True
SUPPORTED_TYPES = ('absolute', 'relative', 'shift_absolute', 'shift_relative', 'identity')
value(p)

Return the distribution parameter value modified by the parameter and type.

Parameters:p (float) – Input parameter to modify.
Returns:
Return type:float
class espei.priors.PriorSpec(name, **parameters)

Bases: object

Specification template for instantiating priors.

SUPPORTED_PRIORS = ('normal', 'uniform', 'triangular', 'zero')
get_prior(value)

Instantiate a prior as described in the spec

Examples

>>> import numpy as np
>>> from espei.priors import PriorSpec
>>> tri_spec = {'name': 'triangular', 'loc_shift_relative': -0.5, 'scale_shift_relative': 0.5, 'c': 0.5}
>>> np.isneginf(PriorSpec(**tri_spec).get_prior(10).logpdf(5.1))
False
>>> np.isneginf(PriorSpec(**tri_spec).get_prior(10).logpdf(4.9))
True
espei.priors.build_prior_specs(prior_spec, parameters)

Get priors from given parameters

Parameters:
  • prior_spec (PriorSpec or dict) – Either a prior spec dict (to instantiate), a PriorSpec, or a list of either. If a list is passed, it must correspond to the parameters.
  • parameters (list) – List of parameters that the priors will be instantiated by
Returns:

Return type:

[PriorSpec]

Examples

>>> s_norm = {'name': 'normal', 'scale_relative': 0.1, 'loc_identity': 1.0}
>>> len(build_prior_specs(s_norm, [10, 100])) == 2
True
>>> s_tri = {'name': 'triangular', 'loc_shift_relative': -0.5, 'scale_shift_relative': 0.5, 'c': 0.5}
>>> from espei.priors import PriorSpec
>>> len(build_prior_specs([s_norm, PriorSpec(**s_tri)], [10, 100])) == 2
True
class espei.priors.rv_zero(*args, **kwargs)

Bases: object

A simple class that mimics the scipy.stats.rv_continuous object’s logpdf method, always returning zero.

This class mainly exists for backwards compatibility where no prior is specified.

Examples

>>> import numpy as np
>>> rv = rv_zero()
>>> np.isclose(rv.logpdf(-np.inf), 0.0)
True
>>> np.isclose(rv.logpdf(1.0), 0.0)
True
>>> np.isclose(rv.logpdf(0.0), 0.0)
True
logpdf(*args, **kwargs)

espei.refdata module

Create a new Mock object. Mock takes several optional arguments that specify the behaviour of the Mock object:

  • spec: This can be either a list of strings or an existing object (a class or instance) that acts as the specification for the mock object. If you pass in an object then a list of strings is formed by calling dir on the object (excluding unsupported magic attributes and methods). Accessing any attribute not in this list will raise an AttributeError.

    If spec is an object (rather than a list of strings) then mock.__class__ returns the class of the spec object. This allows mocks to pass isinstance tests.

  • spec_set: A stricter variant of spec. If used, attempting to set or get an attribute on the mock that isn’t on the object passed as spec_set will raise an AttributeError.

  • side_effect: A function to be called whenever the Mock is called. See the side_effect attribute. Useful for raising exceptions or dynamically changing return values. The function is called with the same arguments as the mock, and unless it returns DEFAULT, the return value of this function is used as the return value.

    If side_effect is an iterable then each call to the mock will return the next value from the iterable. If any of the members of the iterable are exceptions they will be raised instead of returned.

  • return_value: The value returned when the mock is called. By default this is a new Mock (created on first access). See the return_value attribute.

  • wraps: Item for the mock object to wrap. If wraps is not None then calling the Mock will pass the call through to the wrapped object (returning the real result). Attribute access on the mock will return a Mock object that wraps the corresponding attribute of the wrapped object (so attempting to access an attribute that doesn’t exist will raise an AttributeError).

    If the mock has an explicit return_value set then calls are not passed to the wrapped object and the return_value is returned instead.

  • name: If the mock has a name then it will be used in the repr of the mock. This can be useful for debugging. The name is propagated to child mocks.

Mocks can also be called with arbitrary keyword arguments. These will be used to set attributes on the mock after it is created.

espei.rstate module

espei.sublattice_tools module

Utilities for manipulating sublattice models.

espei.sublattice_tools.canonical_sort_key(x)

Wrap strings in tuples so they’ll sort.

Parameters:x (list) – List of strings to sort
Returns:tuple of strings that can be sorted
Return type:tuple
espei.sublattice_tools.canonicalize(configuration, equivalent_sublattices)

Sort a sequence with symmetry. This routine gives the sequence a deterministic ordering while respecting symmetry.

Parameters:
  • configuration ([str]) – Sublattice configuration to sort.
  • equivalent_sublattices ({{int}}) – Indices of ‘configuration’ which should be equivalent by symmetry, i.e., [[0, 4], [1, 2, 3]] means permuting elements 0 and 4, or 1, 2 and 3, respectively, has no effect on the equivalence of the sequence.
Returns:

sorted tuple that has been canonicalized.

Return type:

str

espei.sublattice_tools.endmembers_from_interaction(configuration)

For a given configuration with possible interactions, return all the endmembers

espei.sublattice_tools.generate_endmembers(sublattice_model, symmetry=None)

Return all the unique endmembers by symmetry for a given sublattice model.

Parameters:
  • sublattice_model (list of lists) – General sublattice model, with each sublattice as a sublist.
  • symmetry (list of lists, optional) – List of lists containing symmetrically equivalent sublattice indices. If None (default), all endmembers will be returned.
Returns:

List of endmember tuples

Return type:

list

Examples

>>> subl_model = [['A', 'B'], ['A','B']]
>>> generate_endmembers(subl_model)  # four endmembers
[('A', 'A'), ('A', 'B'), ('B', 'A'), ('B', 'B')]
>>> # three endmembers, ('A', 'B') is equivalent to ('B', 'A') by symmetry.
>>> generate_endmembers(subl_model, [[0, 1]])  # the first and second sublattices are symmetrically equivalent.
[('A', 'A'), ('A', 'B'), ('B', 'B')]
espei.sublattice_tools.generate_interactions(endmembers, order, symmetry)

Returns a list of sorted interactions of a certain order

Parameters:
  • endmembers (list) – List of tuples/strings of all endmembers (including symmetrically equivalent)
  • order (int) – Highest expected interaction order, e.g. ternary interactions should be 3
  • symmetry (list of lists) – List of lists containing symmetrically equivalent sublattice indices, e.g. [[0, 1], [2, 3]] means that sublattices 0 and 1 are equivalent and sublattices 2 and 3 are also equivalent.
Returns:

List of interaction tuples, e.g. [(‘A’, (‘A’, ‘B’))]

Return type:

list

espei.sublattice_tools.generate_symmetric_group(configuration, symmetry)

For a particular configuration and list of sublattices with symmetry, generate all the symmetrically equivalent configurations.

Parameters:
  • configuration (tuple) – Tuple of a sublattice configuration.
  • symmetry (list of lists) – List of lists containing symmetrically equivalent sublattice indices, e.g. [[0, 1], [2, 3]] means that sublattices 0 and 1 are equivalent and sublattices 2 and 3 are also equivalent.
Returns:

Tuple of configuration tuples that are all symmetrically equivalent.

Return type:

tuple

espei.sublattice_tools.interaction_test(configuration, order=None)

Returns True if the configuration has an interaction

Parameters:order (int, optional) – Specific order to check for. E.g. a value of 3 checks for ternary interactions
Returns:True if there is an interaction.
Return type:bool

Examples

>>> configuration = [['A'], ['A','B']]
>>> interaction_test(configuration)
True
>>> interaction_test(configuration, order=2)
True
>>> interaction_test(configuration, order=3)
False
espei.sublattice_tools.recursive_tuplify(x)

Recursively convert a nested list to a tuple

espei.sublattice_tools.sorted_interactions(interactions, max_interaction_order, symmetry)

Return interactions sorted by interaction order

Parameters:
  • interactions (list) – List of tuples/strings of potential interactions
  • max_interaction_order (int) – Highest expected interaction order, e.g. ternary interactions should be 3
  • symmetry (list of lists) – List of lists containing symmetrically equivalent sublattice indices, e.g. [[0, 1], [2, 3]] means that sublattices 0 and 1 are equivalent and sublattices 2 and 3 are also equivalent.
Returns:

Sorted list of interactions

Return type:

list

Notes

Sort by number of full interactions, e.g. (A:A,B) is before (A,B:A,B) The goal is to return a sort key that can sort through multiple interaction orders, e.g. (A:A,B,C), which should be before (A,B:A,B,C), which should be before (A,B,C:A,B,C).

espei.sublattice_tools.tuplify(x)

Convert a list to a tuple, or wrap an object in a tuple if it’s not a list or tuple.

espei.utils module

Utilities for ESPEI

Classes and functions defined here should have some reuse potential.

espei.utils.add_bibtex_to_bib_database(bibtex, bib_db=None)

Add entries from a BibTeX file to the bibliography database

Parameters:
  • bibtex (str) – Either a multiline string, a path, or a file-like object of a BibTeX file
  • bib_db (PickleableTinyDB) – Database to put the BibTeX entries. Defaults to a module-level default database
Returns:

Return type:

The modified bibliographic database

espei.utils.bib_marker_map(bib_keys, markers=None)

Return a dict with reference keys and marker dicts

Parameters:
  • bib_keys
  • markers (list) – List of 2-tuples of (‘fillstyle’, ‘marker’) e.g. [(‘top’, ‘o’), (‘full’, ‘s’)]. Defaults to cycling through the filled markers, the different fill styles.
Returns:

Dictionary with bib_keys as keys, dict values of formatted strings and marker dicts

Return type:

dict

Examples

>>> mm = bib_marker_map(['otis2016', 'bocklund2018'])
>>> mm == {'bocklund2018': {'formatted': 'bocklund2018', 'markers': {'fillstyle': 'none', 'marker': 'o'}}, 'otis2016': {'formatted': 'otis2016', 'markers': {'fillstyle': 'none', 'marker': 'v'}}}
True
espei.utils.build_sitefractions(phase_name, sublattice_configurations, sublattice_occupancies)

Convert nested lists of sublattice configurations and occupancies to a list of dictionaries. The dictionaries map SiteFraction symbols to occupancy values. Note that zero occupancy site fractions will need to be added separately since the total degrees of freedom aren’t known in this function.

Parameters:
  • phase_name (str) – Name of the phase
  • sublattice_configurations ([[str]]) – sublattice configuration
  • sublattice_occupancies ([[float]]) – occupancy of each sublattice
Returns:

a list of site fractions over sublattices

Return type:

[[float]]

espei.utils.database_symbols_to_fit(dbf, symbol_regex='^V[V]?([0-9]+)$')

Return names of the symbols to fit that match the regular expression

Parameters:
  • dbf (Database) – pycalphad Database
  • symbol_regex (str) – Regular expression of the fitting symbols. Defaults to V or VV followed by one or more numbers.
Returns:

Return type:

list

espei.utils.flexible_open_string(obj)

Return the string of a an object that is either file-like, a file path, or the raw string.

Parameters:obj (string-like or file-like) – Either a multiline string, a path, or a file-like object
Returns:
Return type:str
espei.utils.formatted_constituent_array(constituent_array)

Given a constituent array of Species, return the classic CALPHAD-style interaction.

Parameters:constituent_array (list) – List of sublattices, which are lists of Species in that sublattice
Returns:String of the constituent array formatted in the classic CALPHAD style
Return type:str

Examples

>>> from pycalphad import variables as v
>>> const_array = [[v.Species('CU'), v.Species('MG')], [v.Species('MG')]]
>>> formatted_constituent_array(const_array)
'CU,MG:MG'
espei.utils.formatted_parameter(dbf, symbol, unique=True)

Get the deconstructed pretty parts of the parameter/term a symbol belongs to in a Database.

Parameters:
  • dbf (pycalphad.Database) –
  • symbol (string or sympy.Symbol) – Symbol in the Database to get the parameter for.
  • unique (bool) – If True, will raise if more than one parameter containing the symbol is found.
Returns:

A named tuple with the following attributes: phase_name, interaction, symbol, term, parameter_type or term_symbol (which is just the Symbol * temperature term)

Return type:

FormattedParameter

espei.utils.get_dask_config_paths()
espei.utils.optimal_parameters(trace_array, lnprob_array, kth=0)

Return the optimal parameters in the trace based on the highest likelihood. If kth is specified, return the kth set of unique optimal parameters.

Parameters:
  • trace_array (ndarray) – Array of shape (number of chains, iterations, number of parameters)
  • lnprob_array (ndarray) – Array of shape (number of chains, iterations)
  • kth (int) – Zero-indexed optimum. 0 (the default) is the most optimal solution. 1 is the second most optimal, etc.. Only unique solutions will be returned.
Returns:

Return type:

Array of optimal parameters

Notes

It is ok if the calculation did not finish and the arrays are padded with zeros. The number of chains and iterations in the trace and lnprob arrays must match.

espei.utils.parameter_term(expression, symbol)

Determine the term, e.g. T*log(T) that belongs to the symbol in expression

Parameters:
  • expression
  • symbol
espei.utils.popget(d, key, default=None)

Get the key from the dict, returning the default if not found.

Parameters:
  • d (dict) – Dictionary to get key from.
  • key (object) – Key to get from the dictionary.
  • default (object) – Default to return if key is not found in dictionary.
Returns:

Return type:

object

Examples

>>> d = {'ABC': 5.0}
>>> popget(d, 'ZPF', 1.0) == 1.0
True
>>> popget(d, 'ABC', 1.0) == 5.0
True
espei.utils.sigfigs(x, n)

Round x to n significant digits

Module contents

ESPEI