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 SymPy 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, conds, models, output='GM', callables=None, parameters=None, verbose=False, build_gradients=False, build_hessians=False)[source]

Combine compiled callables and callables from conditions into PhaseRecords.

Parameters
  • dbf (Database) – A Database object

  • comps (list) – List of component names

  • phases (list) – List of phase names

  • conds (dict or None) – Conditions for calculation

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

  • parameters (dict, optional) – Maps SymPy 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 SymPy or 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

property func

Alias for field number 0

property grad

Alias for field number 1

property hess

Alias for field number 2

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

Bases: tuple

property cons_func

Alias for field number 0

property cons_hess

Alias for field number 2

property 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[sympy.core.symbol.Symbol]) – Free variables in the sympy_graph. By convention these are usually all instances of StateVariables.

  • constraints (List[sympy.core.expr.Expr]) – List of SymPy expression to compile

  • parameters (Optional[List[sympy.core.symbol.Symbol]]) – Free variables in the sympy_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.

Returns

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(sympy_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 sympy_graph.

Parameters
  • sympy_graph (sympy.core.expr.Expr) – SymPy expression to compile, \(f(x) : \mathbb{R}^{n} \rightarrow \mathbb{R}\), which will corresponds to sympy_graph(variables+parameters)

  • variables (List[sympy.core.symbol.Symbol]) – Free variables in the sympy_graph. By convention these are usually all instances of StateVariables.

  • parameters (Optional[List[sympy.core.symbol.Symbol]]) – Free variables in the sympy_graph. These are typically external parameters that are controlled by the user.

  • wrt (Optional[List[sympy.core.symbol.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 sympy_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.

Returns

Return type

BuildFunctionsResult

Notes

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

Module contents