Kernel Structure

class pystencils.sympyextensions.AssignmentCollection(main_assignments, subexpressions=None, simplification_hints=None, subexpression_symbol_generator=None)

A collection of equations with subexpression definitions, also represented as assignments, that are used in the main equations. AssignmentCollection can be passed to simplification methods. These simplification methods can change the subexpressions, but the number and left hand side of the main equations themselves is not altered. Additionally a dictionary of simplification hints is stored, which are set by the functions that create assignment collections to transport information to the simplification system.

Parameters:

  • main_assignments (Union[List[Assignment], Dict[Expr, Expr]]) – List of assignments. Main assignments are characterised, that the right hand side of each assignment is a field access. Thus the generated equations write on arrays.

  • subexpressions (Union[List[Assignment], Dict[Expr, Expr], None]) – List of assignments defining subexpressions used in main equations

  • simplification_hints (Optional[Dict[str, Any]]) – Dict that is used to annotate the assignment collection with hints that are used by the simplification system. See documentation of the simplification rules for potentially required hints and their meaning.

  • subexpression_symbol_generator (Optional[Iterator[Symbol]]) – Generator for new symbols that are used when new subexpressions are added used to get new symbols that are unique for this AssignmentCollection

add_simplification_hint(key, value)

Adds an entry to the simplification_hints dictionary and checks that is does not exist yet.

Return type:

None

Parameters:

  • key (str) –

  • value (Any) –

add_subexpression(rhs, lhs=None, topological_sort=True)

Adds a subexpression to current collection.

Parameters:

  • rhs (Expr) – right hand side of new subexpression

  • lhs (Optional[Symbol]) – optional left hand side of new subexpression. If None a new unique symbol is generated.

  • topological_sort – sort the subexpressions topologically after insertion, to make sure that definition of a symbol comes before its usage. If False, subexpression is appended.

Return type:

Symbol

Returns:

left hand side symbol (which could have been generated)

topological_sort(sort_subexpressions=True, sort_main_assignments=True)

Sorts subexpressions and/or main_equations topologically to make sure symbol usage comes after definition.

Return type:

None

Parameters:

  • sort_subexpressions (bool) –

  • sort_main_assignments (bool) –

property all_assignments: List[Assignment]

Subexpression and main equations as a single list.

property rhs_symbols: Set[Symbol]

All symbols used in the assignment collection, which occur on the rhs of any assignment.

property free_symbols: Set[Symbol]

All symbols used in the assignment collection, which do not occur as left hand sides in any assignment.

property bound_symbols: Set[Symbol]

All symbols which occur on the left hand side of a main assignment or a subexpression.

property rhs_fields

All fields accessed in the assignment collection, which do not occur as left hand sides in any assignment.

property free_fields

All fields accessed in the assignment collection, which do not occur as left hand sides in any assignment.

property bound_fields

All field accessed on the left hand side of a main assignment or a subexpression.

property defined_symbols: Set[Symbol]

All symbols which occur as left-hand-sides of one of the main equations

property operation_count

See count_operations()

dependent_symbols(symbols)

Returns all symbols that depend on one of the passed symbols.

A symbol ‘a’ depends on a symbol ‘b’, if there is an assignment ‘a <- some_expression(b)’ i.e. when ‘b’ is required to compute ‘a’.

Return type:

Set[Symbol]

Parameters:

symbols (Iterable[Symbol]) –

lambdify(symbols, fixed_symbols=None, module=None)

Returns a python function to evaluate this equation collection.

Parameters:

  • symbols (Sequence[Symbol]) – symbol(s) which are the parameter for the created function

  • fixed_symbols (Optional[Dict[Symbol, Any]]) – dictionary with substitutions, that are applied before sympy’s lambdify

  • module – same as sympy.lambdify parameter. Defines which module to use e.g. ‘numpy’

Examples

>>> a, b, c, d = sp.symbols("a b c d")
>>> ac = AssignmentCollection([Assignment(c, a + b), Assignment(d, a**2 + b)],
...                           subexpressions=[Assignment(b, a + b / 2)])
>>> python_function = ac.lambdify([a], fixed_symbols={b: 2})
>>> python_function(4)
{c: 6, d: 18}
copy(main_assignments=None, subexpressions=None)

Returns a copy with optionally replaced main_assignments and/or subexpressions.

Return type:

AssignmentCollection

Parameters:
new_with_substitutions(substitutions, add_substitutions_as_subexpressions=False, substitute_on_lhs=True, sort_topologically=True)

Returns new object, where terms are substituted according to the passed substitution dict.

Parameters:

  • substitutions (Dict) – dict that is passed to sympy subs, substitutions are done main assignments and subexpressions

  • add_substitutions_as_subexpressions (bool) – if True, the substitutions are added as assignments to subexpressions

  • substitute_on_lhs (bool) – if False, the substitutions are done only on the right hand side of assignments

  • sort_topologically (bool) – if subexpressions are added as substitutions and this parameters is true, the subexpressions are sorted topologically after insertion

Return type:

AssignmentCollection

Returns:

New AssignmentCollection where substitutions have been applied, self is not altered.

new_merged(other)

Returns a new collection which contains self and other. Subexpressions are renamed if they clash.

Return type:

AssignmentCollection

Parameters:

other (AssignmentCollection) –

new_filtered(symbols_to_extract)

Extracts equations that have symbols_to_extract as left hand side, together with necessary subexpressions.

Return type:

AssignmentCollection

Returns:

new AssignmentCollection, self is not altered

Parameters:

symbols_to_extract (Iterable[Symbol]) –

new_without_unused_subexpressions()

Returns new collection that only contains subexpressions required to compute the main assignments.

Return type:

AssignmentCollection

new_with_inserted_subexpression(symbol)

Eliminates the subexpression with the given symbol on its left hand side, by substituting it everywhere.

Return type:

AssignmentCollection

Parameters:

symbol (Symbol) –

new_without_subexpressions(subexpressions_to_keep=None)

Returns a new collection where all subexpressions have been inserted.

Return type:

AssignmentCollection