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:
SymEngine: https://github.com/symengine/symengine/issues/1394
SymEngine.py: https://github.com/symengine/symengine.py/issues/294
- 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:
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:
Notes
Default options for compiling the function, gradient and Hessian are defined by
_get_lambdify_options
.