pyoomph.generic.codegen module

class pyoomph.generic.codegen.BaseEquations(*args: Any, **kwargs: Any)

Bases: Equations

These are the parent class for both ODEEquations and Equations. You will rarely have to use this base class directly.

add_functional_minimization(F, with_respect_to=None, *, dimensional_dx=False, dimensional_testfunctions=True, lagrangian=False, coordinate_system=None, destination=None)

Adds the weak form of the functional minimization of W=integral(F dOmega) to the equations.

Parameters:

• F (ExpressionOrNum) – Integrand of the functional.

• with_respect_to (Optional[Union[Expression,List[Expression]]], optional) – Optionally only derive with respect to all shape functions appearing in the listed expressions. Defaults to None, meaning all shape functions in F.

• dimensional_dx (bool, optional) – Consider spatial scaling in the weak form integral. Defaults to False.

• dimensional_testfunctions (bool, optional) – Expand by dimensional testfunctions. Defaults to True.

• lagrangian (bool, optional) – Weak formulation is integrated over the Lagrangian domain. Defaults to False.

• coordinate_system (OptionalCoordinateSystem, optional) – Optional coordinate system. Defaults to the equations’ coordinate system, then parent equations and eventually the problem coordinate system. Defaults to None.

• destination (Optional[str], optional) – Residual destination identifier. Defaults to None.

Returns:

Returns self for chaining.

Return type:

BaseEquations

add_interior_facet_residual(expr, *, destination=None)

Same as add_residual(), but the added residuals are evaluated and considered at the interior facet domain. This is only used for DG methods and requires the property requires_interior_facet_terms to be set in the constructor of the equations.

Parameters:

• expr (Union[Expression, int, float]) – Expression to add to the residuals

• destination (Optional[str]) – Optional residual destination for multiple residuals. Defaults to None.

add_local_function(name, expr)

Adds a local function for the output. This are not degrees of freedom but only calculated node-wise on output. The same can be achieved by using LocalExpressions(…) instead.

Parameters:

• name (str) – name of the local expressions

• expr (Union[ExpressionOrNum,Callable[[],ExpressionOrNum]]) – Expression to be evaluated on the nodes on output.

Returns:

If the expression is a vector, it just returns the vector component names and 0. For a tensor, it returns the tensor components and the dimension of the tensor.

Return type:

Tuple[List[str],int]

add_residual(expr, *, destination=None)

Adds a residual contribution to this equations.

Parameters:

• expr (Union[Expression, int, float]) – The expression or number to be added as a residual.

• destination (Optional[str]) – The destination of the residual. Defaults to None, can be used to specify different residuals.

Return type:

None

before_assigning_equations_postorder(mesh)

This function is called whenever the equations are numbered. The equation tree is traversed and this function is called after applying it on all of the children of this domain.

Override this method to e.g. pin redundant (overconstraining) Lagrange multipliers with the InterfaceEquations.pin_redundant_lagrange_multipliers() method.

Parameters:

mesh (Union[InterfaceMesh, MeshFromTemplate1d, MeshFromTemplate2d, MeshFromTemplate3d, ODEStorageMesh]) – The mesh corresponding to the this domain.

before_assigning_equations_preorder(mesh)

This function is called whenever the equations are numbered. The equation tree is traversed and this function is called before applying it on all of the children of this domain.

Override this method to e.g. pin redundant (overconstraining) Lagrange multipliers with the InterfaceEquations.pin_redundant_lagrange_multipliers() method.

Parameters:

mesh (Union[InterfaceMesh, MeshFromTemplate1d, MeshFromTemplate2d, MeshFromTemplate3d, ODEStorageMesh]) – The mesh corresponding to the this domain.

define_fields()

Inherit and specify to define fields (dependent variables), either by using ODEEquations.define_ode_variable() (ODEs inherited from ODEEquations) or Equations.define_scalar_field()/Equations.define_vector_field() (PDEs inherited from Equations)

define_residuals()

Inherit and specify to define residuals for the equations, using add_residual() or add_weak() Any returned expression will be also added to the residuals

Return type:

Optional[Expression]

get_azimuthal_r0_info()

Returns a dict [0,1,2]-> Set[str] with the names of the fields that are pinned at r=0 for azimuthal symmetry. Entry 0 contains the names of the fields that are pinned to zero at r=0 for normal (axisymmetric solves). This pinning is strongly enforced. Entry 1 contains the names of the fields that are pinned at r=0 for azimuthal eigensolves with m=1. This pinning is implemented by modifying the eigenproblem matrices. Entry 2 contains the names of the fields that are pinned at r=0 for azimuthal eigensolves with m>=2. This pinning is implemented by modifying the eigenproblem matrices.

get_element_dimension()

Returns the element dimension of the domain where the equations are defined.

get_nodal_dimension()

Returns the nodal (Eulerian) dimension of the domain where the equations are defined.

get_normal()

Returns the normal of this domain. This is only possible if the domain is either a boundary or a bulk domain with co-dimension 1.

Note that var("normal") is essentially the same.

get_parent_domain()

If this domain is a subdomain of another domain, i.e. a boundary, this function returns the parent domain. Otherwise, it returns None.

Return type:

Optional[FiniteElementCodeGenerator]

requires_interior_facet_terms: bool

Set this to true if you require internal facet contributions for DG methods, at best in the constructor

class pyoomph.generic.codegen.Equations(*args: Any, **kwargs: Any)

Bases: BaseEquations

Equations to be solved on a domain, i.e. including spatial coordinates. Add unknown fields by overriding the define_fields() method and residuals by overriding the define_residuals() method.

See BaseEquations for further methods.

activate_coordinates_as_dofs(coordinate_space=None)

Activates the coordinates as degrees of freedom (dofs) for a moving mesh. You must then add residuals in the define_residuals method for the field “mesh”, e.g.

def define_residuals(self):

x,xtest=var_and_test(“mesh”) X=var(“lagrangian”) self.add_weak(grad(x-X,lagrangian=True),grad(xtest,lagrangian=True),lagrangian=True)

for a Laplace-smoothed mesh

Parameters:

coordinate_space (Optional[str]) – The coordinate space to be set as the coordinate space for the element. Valid options are “C2TB”, “C2”, “C1TB”, or “C1”. If not provided, the coordinate space will not be set.

Raises:

ValueError – If the provided coordinate space is not one of the valid options.

Return type:

None

Returns:

None

define_scalar_field(name, space, scale=None, testscale=None, discontinuous_refinement_exponent=None)

Define a scalar field on this domain. Must be called within the specified implementation of the method define_fields().

Parameters:

• name (str) – The name of the vector field.

• space (FiniteElementSpaceEnum) – The finite element space on which the vector field is defined.

• scale (ExpressionNumOrNone) – The scale for the vector field for nondimensionalization. Defaults to None.

• testscale (ExpressionNumOrNone) – The scale for the test function of the vector field for nondimensionalization. Defaults to None.

• discontinuous_refinement_exponent (Optional[float]) – The exponent for the discontinuous refinement. Defaults to None.

define_vector_field(name, space, dim=None, scale=None, testscale=None)

Define a vector field on this domain. Must be called within the specified implementation of the method define_fields().

Parameters:

• name (str) – The name of the vector field.

• space (FiniteElementSpaceEnum) – The finite element space on which the vector field is defined.

• dim (Optional[int]) – The dimension of the vector field. If not provided, it defaults to the nodal dimension.

• scale (ExpressionNumOrNone) – The scale for the vector field for nondimensionalization. Defaults to None.

• testscale (ExpressionNumOrNone) – The scale for the test function of the vector field for nondimensionalization. Defaults to None.

get_opposite_parent_domain(raise_error_if_none=True)

Returns the bulk domain at the opposite side of this interface.

Parameters:

raise_error_if_none (bool) – If there is no opposite side set, raise an error. Otherwise, just None is returned.

Return type:

Optional[FiniteElementCodeGenerator]

Returns:

The bulk domain at the opposite side.

get_opposite_side_of_interface(raise_error_if_none=True)

Returns the interface domain at the opposite side of this interface.

Parameters:

raise_error_if_none (bool) – If there is no opposite side set, raise an error. Otherwise, just None is returned.

Return type:

Optional[FiniteElementCodeGenerator]

Returns:

The interface domain at the opposite side.

get_weak_dirichlet_terms_for_DG(fieldname, value)

Returns the weak Dirichlet terms for a discontinuous Galerkin (DG) formulation. When using a DirichletBC with prefer_weak_for_DG, this method is called. If it returns not None, the DirichletBC is not enforced strongly, but on the basis of the given interface residuals.

Parameters:

• fieldname (str) – Name of the field for which the weak Dirichlet terms are to be returned.

• value (Union[Expression, int, float]) – The desired Dirichlet condition.

Return type:

Union[Expression, int, float, None]

class pyoomph.generic.codegen.GlobalLagrangeMultiplier(*args, only_for_stationary_solve=False, set_zero_on_normal_mode_eigensolve=True, **kwargs)

Bases: ODEEquations

This class allows to define a global Lagrange multiplier that are used to enforce global constraints. It is just a normal ODEEquations but with some additional features, i.e. it can be e.g. deactivated on transient solves.

class pyoomph.generic.codegen.InterfaceEquations(*args: Any, **kwargs: Any)

Bases: Equations

Same as normal Equations but with some extra functions for equations defined on interfaces.

get_opposite_parent_equations(of_type=None)

Returns the Equations in the parent bulk domain at the opposite side of this interface. When setting the attribute required_opposite_parent_type, of_type can be omitted to get the expected parent equations.

This method is useful to e.g. get the mass density from a Navier-Stokes equation in the opposite bulk domain, e.g. for mass transfer processes at the interface.

Parameters:

of_type (Optional[Type[Equations]]) – The type of the equations to be returned. If not provided, the required_opposite_parent_type has to be set.

get_parent_equations(of_type=None)

Returns the Equations in the parent bulk domain of a given type. When setting the attribute required_parent_type, of_type can be omitted to get the expected parent equations.

This method is useful to e.g. get the mass density from a Navier-Stokes equation in the bulk domain, e.g. for mass transfer processes at the interface.

Parameters:

of_type (Optional[Type[Equations]]) – The type of the equations to be returned. If not provided, the required_parent_type has to be set.

pin_redundant_lagrange_multipliers(mesh, lagr, depvars, opposite_interface=[])

Allows to pin redundant (overconstraining) Lagrange multipliers. A field of Lagrange multipliers usually enforces some constraint depending on depvars (and poentially degrees at the opposite_interface). If all these degrres are pinned, the Lagrange multiplier lagr is pinned and set to zero as well.

Parameters:

• mesh (InterfaceMesh) – The current mesh must be passed

• lagr (str) – Name of the Lagrange multiplier field to be automatically pinned if necessary

• depvars (Union[str, List[str], Tuple[str, ...]]) – Single or multiple variables that occur in the constraint.

• opposite_interface (Union[str, List[str], Tuple[str, ...]]) – Optional dependencies on the opposite side of the interface.

required_opposite_parent_type: Optional[Type[Equations]] = None

If set to a particular Equations class, pyoomph will check whether we have indeed these equations at the opposite bulk side of this interface

required_parent_type: Optional[Type[Equations]] = None

If set to a particular Equations class, pyoomph will check whether we have indeed these equations in the bulk

class pyoomph.generic.codegen.ODEEquations(*args: Any, **kwargs: Any)

Bases: BaseEquations

Class representing a set of ordinary differential equations (ODEs). Add unknowns by overriding the define_fields() method and residuals by overriding the define_residuals() method.

See BaseEquations for further methods.

__init__()

Call this method to initialize the ODE equations, e.g. usually you pass parameters here which can be then used in the equations within the define_residuals method. Also, you must call super().__init__() in the derived class before anything else.

define_ode_variable(*names, scale=None, testscale=None)

Defines the ODE variables.

Parameters:

• *names (str) – Variable length argument representing the names of the ODE variable(s).

• scale (Union[Expression, int, float, None]) – Optional scaling factor for the ODE variable(s).

• testscale (Union[Expression, int, float, None]) – Optional scaling factor for the test functions associated with the ODE variable(s).

Return type:

None

expand_additional_field(name, dimensional, expression, in_domain, no_jacobian, no_hessian, where)

Expands additional fields for the ODEs.

Parameters:

• name (str) – The name of the additional field.

• dimensional (bool) – A boolean indicating if the field is dimensional.

• expression (Expression) – The expression defining the additional field.

• in_domain (FiniteElementCode) – The finite element code representing the domain.

• no_jacobian (bool) – A boolean indicating if the Jacobian should not be computed.

• no_hessian (bool) – A boolean indicating if the Hessian should not be computed.

• where (str) – The location where the additional field is expanded.

Returns:

The expanded additional field.

Return type:

Expression

get_coordinate_system()

Returns the base coordinate system.

Returns:

The base coordinate system.

Return type:

BaseCoordinateSystem

get_mesh()

Returns the ODE storage mesh.

Returns:

The ODE storage mesh.

Return type:

ODEStorageMesh

get_parent_domain()

Returns the parent domain.

Returns:

The parent domain.

Return type:

None

on_apply_boundary_conditions(mesh)

Applies boundary conditions to the ODEs.

Parameters:

mesh (Union[InterfaceMesh, MeshFromTemplate1d, MeshFromTemplate2d, MeshFromTemplate3d, ODEStorageMesh]) – The mesh to which the boundary conditions are applied.

pin(**kwargs)

Pins the specified degrees of freedom (DOFs).

Parameters:

**kwargs (Union[bool, float]) – Keyword arguments representing the DOFs to be pinned and their values. If assigning True, we just fix the current value, otherwise, the provided value is set.

unpin(*args)

Unpins the specified degrees of freedom (DOFs).

Parameters:

*args (str) – Variable length argument representing the DOFs to be unpinned.

class pyoomph.generic.codegen.ResidualContribution(r, destination=None)

Bases: BaseEquations

A class to add an arbitrary residual contribution to the equations. This is useful to add additional terms to the equations that are not covered by the standard weak formulation. Essentially, it just adds r to the residuals.

Parameters:

• r (Union[Expression, int, float, str]) – The residual to add (can be e.g. a weak() contribution).

• destination (Optional[str]) – The residual destination of the weak contribution. Can be used to define multiple residuals.

class pyoomph.generic.codegen.ScalarField(name, space, scale=None, testscale=None, residual=None)

Bases: Equations

Introduces a scalar field with the given name and the given space. Residuals can be either added in the constructor or by combining with WeakContribution.

Parameters:

• name (str) – Name of the scalar field

• space (Literal['C1', 'C1TB', 'C2', 'C2TB', 'D1', 'D1TB', 'D2', 'D2TB', 'DL', 'D0']) – Space of the scalar field

• scale (Union[Expression, int, float, None]) – Optional scaling of the field (default is 1)

• testscale (Union[Expression, int, float, None]) – Optional scaling of the test function (default is 1)

• residual (Union[Expression, int, float, None]) – Optional residual to be added. Formulate it in terms of the scalar field and the test function.

class pyoomph.generic.codegen.VectorField(name, space, scale=None, testscale=None, residual=None, dim=None)

Bases: Equations

Introduces a vector field with the given name and the given space. Residuals can be either added in the constructor or by combining with WeakContribution.

Parameters:

• name (str) – Name of the scalar field

• space (Literal['C1', 'C1TB', 'C2', 'C2TB', 'D1', 'D1TB', 'D2', 'D2TB', 'DL', 'D0']) – Space of the scalar field

• scale (Union[Expression, int, float, None]) – Optional scaling of the field (default is 1)

• testscale (Union[Expression, int, float, None]) – Optional scaling of the test function (default is 1)

• residual (Union[Expression, int, float, None]) – Optional residual to be added. Formulate it in terms of the scalar field and the test function.

• dim (Optional[int]) – Vector dimension. If not set, it will be taken by the dimension of the mesh coordinates, i.e. the nodal dimension

class pyoomph.generic.codegen.WeakContribution(a, b, dimensional_dx=False, lagrangian=False, coordinate_system=None, destination=None)

Bases: BaseEquations

A class to add an arbitrary weak contribution to the equations. This is useful to add additional terms to the equations that are not covered by the standard weak formulation. Essentially, it just adds weak(a,b) to the residuals.

Parameters:

• a (Union[Expression, int, float, str]) – The lhs of the weak() contribution.

• b (Union[Expression, str]) – The rhs (usually a testfunction()) of the weak() contribution.

• dimensional_dx (bool) – If set to True, the weak contribution is treated as a dimensional contribution, i.e. spatial integration dx will carry dimension.

• lagrangian (bool) – If set to True, the weak contribution is integrated in the Lagrangian frame of reference.

• coordinate_system (Optional[BaseCoordinateSystem]) – The coordinate system in which the weak contribution is defined. If not set, the coordinate system of the equations or the problem is used.

• destination (Optional[str]) – The residual destination of the weak contribution. Can be used to define multiple residuals.