espei.error_functions package¶
Submodules¶
espei.error_functions.activity_error module¶
Calculate error due to measured activities.
-
espei.error_functions.activity_error.
calculate_activity_error
(dbf, comps, phases, datasets, parameters=None, phase_models=None, callables=None, data_weight=1.0)¶ Return the sum of square error from activity data
Parameters: - 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
- parameters (dict) – Dictionary of symbols that will be overridden in pycalphad.equilibrium
- phase_models (dict) – Phase models to pass to pycalphad calculations
- callables (dict) – Callables to pass to pycalphad
- data_weight (float) – Weight for standard deviation of activity measurements, dimensionless. Corresponds to the standard deviation of differences in chemical potential in typical measurements of activity, in J/mol.
Returns: A single float of the sum of square errors
Return type: float
Notes
General procedure: 1. Get the datasets 2. For each dataset
- Calculate reference state equilibrium
- Calculate current chemical potentials
- Find the target chemical potentials
- Calculate error due to chemical potentials
-
espei.error_functions.activity_error.
chempot_error
(sample_chempots, target_chempots, std_dev=10.0)¶ Return the sum of square error from chemical potentials
- sample_chempots : numpy.ndarray
- Calculated chemical potentials
- target_activity : numpy.ndarray
- Chemical potentials to target
- std_dev : float
- Standard deviation of activity measurements in J/mol. Corresponds to the standard deviation of differences in chemical potential in typical measurements of activity.
Returns: Error due to chemical potentials Return type: float
-
espei.error_functions.activity_error.
target_chempots_from_activity
(component, target_activity, temperatures, reference_result)¶ Return an array of experimental chemical potentials for the component
Parameters: - component (str) – Name of the component
- target_activity (numpy.ndarray) – Array of experimental activities
- temperatures (numpy.ndarray) – Ravelled array of temperatures (of same size as
exp_activity
). - reference_result (xarray.Dataset) – Dataset of the equilibrium reference state. Should contain a singe point calculation.
Returns: Array of experimental chemical potentials
Return type: numpy.ndarray
espei.error_functions.context module¶
Convenience function to create a context for the built in error functions
-
espei.error_functions.context.
setup_context
(dbf, datasets, symbols_to_fit=None, data_weights=None, make_callables=True)¶ Set up a context dictionary for calculating error.
Parameters: - dbf (Database) – A pycalphad Database that will be fit
- datasets (PickleableTinyDB) – A database of single- and multi-phase data to fit
- symbols_to_fit (list of str) – List of symbols in the Database that will be fit. If None (default) are passed, then all parameters prefixed with VV followed by a number, e.g. VV0001 will be fit.
Notes
A copy of the Database is made and used in the context. To commit changes back to the original database, the dbf.symbols.update method should be used.
espei.error_functions.equilibrium_thermochemical_error module¶
Calculate error due to equilibrium thermochemical properties.
-
class
espei.error_functions.equilibrium_thermochemical_error.
EqPropData
(dbf, species, phases, potential_conds, composition_conds, models, params_keys, phase_records, output, samples, weight, reference)¶ Bases:
tuple
-
composition_conds
¶ Alias for field number 4
-
dbf
¶ Alias for field number 0
-
models
¶ Alias for field number 5
-
output
¶ Alias for field number 8
-
params_keys
¶ Alias for field number 6
-
phase_records
¶ Alias for field number 7
-
phases
¶ Alias for field number 2
-
potential_conds
¶ Alias for field number 3
-
reference
¶ Alias for field number 11
-
samples
¶ Alias for field number 9
-
species
¶ Alias for field number 1
-
weight
¶ Alias for field number 10
-
-
espei.error_functions.equilibrium_thermochemical_error.
build_eqpropdata
(data: <Mock name='mock.database.Document' id='140538679784272'>, dbf: <Mock name='mock.Database' id='140538679723664'>, parameters: Optional[Dict[str, float]] = None, data_weight_dict: Optional[Dict[str, float]] = None) → espei.error_functions.equilibrium_thermochemical_error.EqPropData¶ Build EqPropData for the calculations corresponding to a single dataset.
Parameters: - data (tinydb.database.Document) – Document corresponding to a single ESPEI dataset.
- dbf (Database) – Database that should be used to construct the Model and PhaseRecord objects.
- parameters (Optional[Dict[str, float]]) – Mapping of parameter symbols to values.
- data_weight_dict (Optional[Dict[str, float]]) – Mapping of a data type (e.g. HM or SM) to a weight.
Returns: Return type:
-
espei.error_functions.equilibrium_thermochemical_error.
calc_prop_differences
(eqpropdata: espei.error_functions.equilibrium_thermochemical_error.EqPropData, parameters: <Mock name='mock.ndarray' id='140538680644944'>, approximate_equilibrium: Optional[bool] = False) → Tuple[<Mock name='mock.ndarray' id='140538680644944'>, <Mock name='mock.ndarray' id='140538680644944'>]¶ Calculate differences between the expected and calculated values for a property
Parameters: - eqpropdata (EqPropData) – Data corresponding to equilibrium calculations for a single datasets.
- parameters (np.ndarray) – Array of parameters to fit. Must be sorted in the same symbol sorted order used to create the PhaseRecords.
- approximate_equilibrium (Optional[bool]) – Whether or not to use an approximate version of equilibrium that does
not refine the solution and uses
starting_point
instead.
Returns: Pair of * differences between the calculated property and expected property * weights for this dataset
Return type: Tuple[np.ndarray, np.ndarray]
-
espei.error_functions.equilibrium_thermochemical_error.
calculate_equilibrium_thermochemical_probability
(eq_thermochemical_data: Sequence[espei.error_functions.equilibrium_thermochemical_error.EqPropData], parameters: <Mock name='mock.ndarray' id='140538680644944'>, approximate_equilibrium: Optional[bool] = False) → float¶ Calculate the total equilibrium thermochemical probability for all EqPropData
Parameters: - eq_thermochemical_data (Sequence[EqPropData]) – List of equilibrium thermochemical data corresponding to the datasets.
- parameters (np.ndarray) – Values of parameters for this iteration to be updated in PhaseRecords.
- approximate_equilibrium (Optional[bool], optional) –
- eq_thermochemical_data –
Returns: Sum of log-probability for all thermochemical data.
Return type: float
-
espei.error_functions.equilibrium_thermochemical_error.
get_equilibrium_thermochemical_data
()¶ Get all the EqPropData for each matching equilibrium thermochemical dataset in the datasets
Parameters: - dbf (Database) – Database with parameters to fit
- comps (Sequence[str]) – List of pure element components used to find matching datasets.
- phases (Sequence[str]) – List of phases used to search for matching datasets.
- datasets (PickleableTinyDB) – Datasets that contain single phase data
- parameters (Optional[Dict[str, float]]) – Mapping of parameter symbols to values.
- data_weight_dict (Optional[Dict[str, float]]) – Mapping of a data type (e.g. HM or SM) to a weight.
Notes
Found datasets will be subsets of the components and phases. Equilibrium thermochemical data is assumed to be any data that does not have the solver key, and does not have an output of ZPF or ACR (which correspond to different data types than can be calculated here.)
Returns: Return type: Sequence[EqPropData]
espei.error_functions.non_equilibrium_thermochemical_error module¶
Calculate error due to thermochemical quantities: heat capacity, entropy, enthalpy.
-
espei.error_functions.non_equilibrium_thermochemical_error.
calculate_non_equilibrium_thermochemical_probability
(dbf, thermochemical_data, parameters=None)¶ Calculate the weighted single phase error in the Database
Parameters: - dbf (pycalphad.Database) – Database to consider
- thermochemical_data (list) – List of thermochemical data dicts
- parameters (np.ndarray) – Array of parameters to calculate the error with.
Returns: A single float of the residual sum of square errors
Return type: float
Notes
There are different single phase values, HM_MIX, SM_FORM, CP_FORM, etc. Each of these have different units and the error cannot be compared directly. To normalize all of the errors, a normalization factor must be used. Equation 2.59 and 2.60 in Lukas, Fries, and Sundman “Computational Thermodynamics” shows how this can be considered. Each type of error will be weighted by the reciprocal of the estimated uncertainty in the measured value and conditions. The weighting factor is calculated by $ p_i = (Delta L_i)^{-1} $ where $ Delta L_i $ is the uncertainty in the measurement. We will neglect the uncertainty for quantities such as temperature, assuming they are small.
-
espei.error_functions.non_equilibrium_thermochemical_error.
calculate_points_array
(phase_constituents, configuration, occupancies=None)¶ Calculate the points array to use in pycalphad calculate calls.
Converts the configuration data (and occupancies for mixing data) into the points array by looking up the indices in the active phase constituents.
Parameters: - phase_constituents (list) – List of active constituents in a phase
- configuration (list) – List of the sublattice configuration
- occupancies (list) – List of sublattice occupancies. Required for mixing sublattices, otherwise takes no effect.
Returns: Return type: numpy.ndarray
Notes
Errors will be raised if components in the configuration are not in the corresponding phase constituents sublattice.
-
espei.error_functions.non_equilibrium_thermochemical_error.
get_prop_samples
(dbf, comps, phase_name, desired_data)¶ Return data values and the conditions to calculate them by pycalphad calculate from the datasets
Parameters: - dbf (pycalphad.Database) – Database to consider
- comps (list) – List of active component names
- phase_name (str) – Name of the phase to consider from the Database
- desired_data (list) – List of dictionary datasets that contain the values to sample
Returns: Dictionary of condition kwargs for pycalphad’s calculate and the expected values
Return type: dict
-
espei.error_functions.non_equilibrium_thermochemical_error.
get_thermochemical_data
(dbf, comps, phases, datasets, weight_dict=None, symbols_to_fit=None)¶ Parameters: - 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
- weight_dict (dict) – Dictionary of weights for each data type, e.g. {‘HM’: 200, ‘SM’: 2}
- symbols_to_fit (list) – Parameters to fit. Used to build the models and PhaseRecords.
Returns: List of data dictionaries to iterate over
Return type: list
espei.error_functions.zpf_error module¶
Calculate driving_force due to ZPF tielines.
The general approach is similar to the PanOptimizer rough search method.
- With all phases active, calculate the chemical potentials of the tieline
endpoints via
equilibrium
calls. Done inestimate_hyperplane
. - Calculate the target chemical potentials, which are the average chemical potentials of all of the current chemical potentials at the tieline endpoints.
- Calculate the current chemical potentials of the desired single phases
- The error is the difference between these chemical potentials
There’s some special handling for tieline endpoints where we do not know the composition conditions to calculate chemical potentials at.
-
class
espei.error_functions.zpf_error.
PhaseRegion
(region_phases, potential_conds, comp_conds, phase_flags, dbf, species, phases, models, phase_records)¶ Bases:
tuple
-
comp_conds
¶ Alias for field number 2
-
dbf
¶ Alias for field number 4
-
models
¶ Alias for field number 7
-
phase_flags
¶ Alias for field number 3
-
phase_records
¶ Alias for field number 8
-
phases
¶ Alias for field number 6
-
potential_conds
¶ Alias for field number 1
-
region_phases
¶ Alias for field number 0
-
species
¶ Alias for field number 5
-
-
espei.error_functions.zpf_error.
calculate_zpf_error
(zpf_data: Sequence[Dict[str, Any]], parameters: <Mock name='mock.ndarray' id='140538680644944'> = None, data_weight: int = 1.0, approximate_equilibrium: bool = False)¶ Calculate error due to phase equilibria data
- zpf_data : list
- Datasets that contain single phase data
- phase_models : dict
- Phase models to pass to pycalphad calculations
- parameters : np.ndarray
- Array of parameters to calculate the error with.
- callables : dict
- Callables to pass to pycalphad
- data_weight : float
- Scaling factor for the standard deviation of the measurement of a tieline which has units J/mol. The standard deviation is 1000 J/mol and the scaling factor defaults to 1.0.
- approximate_equilibrium : bool
- Whether or not to use an approximate version of equilibrium that does
not refine the solution and uses
starting_point
instead.
Returns: Log probability of ZPF error Return type: float Notes
The physical picture of the standard deviation is that we’ve measured a ZPF line. That line corresponds to some equilibrium chemical potentials. The standard deviation is the standard deviation of those ‘measured’ chemical potentials.
-
espei.error_functions.zpf_error.
driving_force_to_hyperplane
(target_hyperplane_chempots: <Mock name='mock.ndarray' id='140538680644944'>, comps: Sequence[str], phase_region: espei.error_functions.zpf_error.PhaseRegion, vertex_idx: int, parameters: <Mock name='mock.ndarray' id='140538680644944'>, approximate_equilibrium: bool = False) → float¶ Calculate the integrated driving force between the current hyperplane and target hyperplane.
-
espei.error_functions.zpf_error.
estimate_hyperplane
(phase_region: espei.error_functions.zpf_error.PhaseRegion, parameters: <Mock name='mock.ndarray' id='140538680644944'>, approximate_equilibrium: bool = False) → <Mock name='mock.ndarray' id='140538680644944'>¶ Calculate the chemical potentials for the target hyperplane, one vertex at a time
Notes
This takes just one set of phase equilibria, a phase region, e.g. a dataset point of [[‘FCC_A1’, [‘CU’], [0.1]], [‘LAVES_C15’, [‘CU’], [0.3]]] and calculates the chemical potentials given all the phases possible at the given compositions. Then the average chemical potentials of each end point are taken as the target hyperplane for the given equilibria.
-
espei.error_functions.zpf_error.
extract_conditions
(all_conditions: Dict[<Mock name='mock.variables.StateVariable' id='140538680646480'>, <Mock name='mock.ndarray' id='140538680644944'>], idx: int) → Dict[<Mock name='mock.variables.StateVariable' id='140538680646480'>, float]¶ Conditions are either scalar or 1d arrays for the conditions in the entire dataset. This function extracts the condition corresponding to the current region, based on the index in the 1d condition array.
-
espei.error_functions.zpf_error.
extract_phases_comps
(phase_region)¶ Extract the phase names, phase compositions and any phase flags from each tie-line point in the phase region
-
espei.error_functions.zpf_error.
get_zpf_data
()¶ Return the ZPF data used in the calculation of ZPF error
Parameters: - comps (list) – List of active component names
- phases (list) – List of phases to consider
- datasets (espei.utils.PickleableTinyDB) – Datasets that contain single phase data
- parameters (dict) – Dictionary mapping symbols to optimize to their initial values
Returns: List of data dictionaries with keys
weight
,data_comps
andphase_regions
.data_comps
are the components for the data in question.phase_regions
are the ZPF phases, state variables and compositions.Return type: list
Module contents¶
Functions for calculating error.