pycalphad.codegen package#

Submodules#

pycalphad.codegen.callables module#

pycalphad.codegen.callables.build_callables(dbf, comps, phases, models, parameter_symbols=None, output='GM', build_gradients=True, build_hessians=False, additional_statevars=None)[source]#

Create a compiled callables dictionary.

Parameters:
  • dbf (Database) – A Database object

  • comps (list) – List of component names

  • phases (list) – List of phase names

  • models (dict) – Dictionary of {phase_name: Model subclass}

  • parameter_symbols (list, optional) – List of string or SymEngine Symbols that will be overridden in the callables.

  • output (str, optional) – Output property of the particular Model to sample. Defaults to ‘GM’

  • build_gradients (bool, optional) – Whether or not to build gradient functions. Defaults to True.

  • build_hessians (bool, optional) – Whether or not to build Hessian functions. Defaults to False.

  • additional_statevars (set, optional) – State variables to include in the callables that may not be in the models (e.g. from conditions)

  • verbose (bool, optional) – Print the name of the phase when its callables are built

Returns:

callables – Dictionary of keyword argument callables to pass to equilibrium. Maps {‘output’ -> {‘function’ -> {‘phase_name’ -> AutowrapFunction()}}.

Return type:

dict

Notes

All the state variables used in calculations must be specified. If these are not specified as state variables of the models (e.g. often the case for v.N), then it must be supplied by the additional_statevars keyword argument.

Examples

>>> from pycalphad import Database, equilibrium, variables as v
>>> from pycalphad.codegen.callables import build_callables
>>> from pycalphad.core.utils import instantiate_models
>>> dbf = Database('AL-NI.tdb')
>>> comps = ['AL', 'NI', 'VA']
>>> phases = ['LIQUID', 'AL3NI5', 'AL3NI2', 'AL3NI']
>>> models = instantiate_models(dbf, comps, phases)
>>> callables = build_callables(dbf, comps, phases, models, additional_statevars={v.P, v.T, v.N})
>>> 'GM' in callables.keys()
True
>>> 'massfuncs' in callables['GM']
True
>>> conditions = {v.P: 101325, v.T: 2500, v.X('AL'): 0.2}
>>> equilibrium(dbf, comps, phases, conditions, callables=callables)
pycalphad.codegen.callables.build_phase_records(dbf, comps, phases, state_variables, models, output='GM', callables=None, parameters=None, verbose=False, build_gradients=True, build_hessians=True)[source]#

Combine compiled callables and callables from conditions into PhaseRecords.

Parameters:
  • dbf (Database) – A Database object

  • comps (List[Union[str, v.Species]]) – List of active pure elements or species.

  • phases (list) – List of phase names

  • state_variables (Iterable[v.StateVariable]) – State variables used to produce the generated functions.

  • models (Mapping[str, Model]) – Mapping of phase names to model instances

  • parameters (dict, optional) – Maps SymEngine Symbol to numbers, for overriding the values of parameters in the Database.

  • callables (dict, optional) – Pre-computed callables. If None are passed, they will be built. Maps {‘output’ -> {‘function’ -> {‘phase_name’ -> AutowrapFunction()}}

  • output (str) – Output property of the particular Model to sample

  • verbose (bool, optional) – Print the name of the phase when its callables are built

  • build_gradients (bool) – Whether or not to build gradient functions. Defaults to False. Only takes effect if callables are not passed.

  • build_hessians (bool) – Whether or not to build Hessian functions. Defaults to False. Only takes effect if callables are not passed.

Returns:

Dictionary mapping phase names to PhaseRecord instances.

Return type:

dict

Notes

If callables are passed, don’t rebuild them. This means that the callables are not checked for incompatibility. Users of build_callables are responsible for ensuring that the state variables, parameters and models used to construct the callables are compatible with the ones used to build the constraints and phase records.

pycalphad.codegen.sympydiff_utils module#

This module defines functions for compiling symbolic SymEngine expressions into fast callable functions.

The SymEngine lambdify function is used to compile the functions using a particular backend, with or without common subexpression elimination (CSE).

By default, the LLVM backend is used with the opt_level=0 option and common subexpression elimination is on, as defined by the module constants:

LAMBDIFY_DEFAULT_BACKEND = 'llvm'
LAMBDIFY_DEFAULT_CSE = True
LAMBDIFY_DEFAULT_LLVM_OPT_LEVEL = 0

Note that as of February 2020, SymEngine only supports using 'lambda' or 'llvm' backends. The LLVM backend uses the LLVM compiler to compile the expressions, and is slower to build the callable functions than the Lambda backend, though in principle the LLVM runtime performance can be better as LLVM can optimize the functions.

Callables produced with the Lambda backend cannot be pickled, since SymEngine does not define how its objects should be serialized. This is important to packages that may want to parallelize pycalphad calls and pickle the callable functions or PhaseRecords. The following issues track this behavior:

class pycalphad.codegen.sympydiff_utils.BuildFunctionsResult(func, grad, hess)#

Bases: tuple

func#

Alias for field number 0

grad#

Alias for field number 1

hess#

Alias for field number 2

class pycalphad.codegen.sympydiff_utils.ConstraintFunctions(cons_func, cons_jac, cons_hess)#

Bases: tuple

cons_func#

Alias for field number 0

cons_hess#

Alias for field number 2

cons_jac#

Alias for field number 1

pycalphad.codegen.sympydiff_utils.build_constraint_functions(variables, constraints, parameters=None, func_options=None, jac_options=None, hess_options=None)[source]#

Build callables functions for the constraints, constraint Jacobian, and constraint Hessian.

Parameters:
  • variables (List[symengine.Symbol]) – Free variables in the symengine_graph. By convention these are usually all instances of StateVariables.

  • constraints (List[symengine.Basic]) – List of SymEngine expression to compile

  • parameters (Optional[List[symengine.Symbol]]) – Free variables in the symengine_graph. These are typically external parameters that are controlled by the user.

  • func_options (None, optional) – Options to pass to lambdify when compiling the function.

  • jac_options (Optional[Dict[str, str]]) – Options to pass to lambdify when compiling the Jacobian.

  • hess_options (Optional[Dict[str, str]]) – Options to pass to lambdify when compiling Hessian.

Return type:

ConstraintFunctions

Notes

Default options for compiling the function, gradient and Hessian are defined by _get_lambdify_options.

pycalphad.codegen.sympydiff_utils.build_functions(symengine_graph, variables, parameters=None, wrt=None, include_obj=True, include_grad=False, include_hess=False, func_options=None, grad_options=None, hess_options=None)[source]#

Build function, gradient, and Hessian callables of the symengine_graph.

Parameters:
  • symengine_graph (symengine.Basic) – symengine expression to compile, \(f(x) : \mathbb{R}^{n} \rightarrow \mathbb{R}\), which will corresponds to symengine_graph(variables+parameters)

  • variables (List[symengine.Symbol]) – Free variables in the symengine_graph. By convention these are usually all instances of StateVariables.

  • parameters (Optional[List[symengine.Symbol]]) – Free variables in the symengine_graph. These are typically external parameters that are controlled by the user.

  • wrt (Optional[List[symengine.Symbol]]) – Variables to differentiate with respect to for the gradient and Hessian callables. If None, will fall back to variables.

  • include_obj (Optional[bool]) – Whether to build the symengine_graph callable, \(f(x) : \mathbb{R}^{n} \rightarrow \mathbb{R}\)

  • include_grad (Optional[bool]) – Whether to build the gradient callable, \(\pmb{g}(x) = \nabla f(x) : \mathbb{R}^{n} \rightarrow \mathbb{R}^{n}\)

  • include_hess (Optional[bool]) – Whether to build the Hessian callable, \(\mathbb{H}(x) = \nabla^2 f(x) : \mathbb{R}^{n} \rightarrow \mathbb{R}^{n \times n}\)

  • func_options (Optional[Dict[str, str]]) – Options to pass to lambdify when compiling the function.

  • grad_options (Optional[Dict[str, str]]) – Options to pass to lambdify when compiling the gradient.

  • hess_options (Optional[Dict[str, str]]) – Options to pass to lambdify when compiling Hessian.

Return type:

BuildFunctionsResult

Notes

Default options for compiling the function, gradient and Hessian are defined by _get_lambdify_options.

Module contents#