4.2.1.5 pde.grids.boundaries.local module

This module contains classes for handling a single boundary of a non-periodic axis. Since an axis has two boundary, we simply distinguish them by a boolean flag upper, which is True for the side of the axis with the larger coordinate.

The module currently supports the following standard boundary conditions:

• DirichletBC: Imposing the value of a field at the boundary

• NeumannBC: Imposing the derivative of a field in the outward normal direction at the boundary

• MixedBC: Imposing the derivative of a field in the outward normal direction proportional to its value at the boundary

• CurvatureBC: Imposing the second derivative (curvature) of a field at the boundary

There are also variants of these boundary conditions that only affect the normal components of a vector or tensor field: NormalDirichletBC, NormalNeumannBC, NormalMixedBC, and NormalCurvatureBC.

Finally, there are more specialized classes, which offer greater flexibility, but might also require a slightly deeper understanding for proper use:

• ExpressionValueBC: Imposing the value of a field at the boundary based on a mathematical expression or a python function.

• ExpressionDerivativeBC: Imposing the derivative of a field in the outward normal direction at the boundary based on a mathematical expression or a python function.

• ExpressionMixedBC: Imposing a mixed (Robin) boundary condition using mathematical expressions or python functions.

• UserBC: Allows full control for setting virtual points, values, or derivatives. The boundary conditions are never enforced automatically. It is thus the user’s responsibility to ensure virtual points are set correctly before operators are applied. To set boundary conditions a dictionary {TARGET: value} must be supplied as argument args to set_ghost_cells() or the numba equivalent. Here, TARGET determines how the value is interpreted and what boundary condition is actually enforced: the value of the virtual points directly (virtual_point), the value of the field at the boundary (value) or the outward derivative of the field at the boundary (derivative).

Note that derivatives are generally given in the direction of the outward normal vector, such that positive derivatives correspond to a function that increases across the boundary.

Inheritance structure of the classes:

class BCBase(grid, axis, upper, *, rank=0)

Bases: object

Represents a single boundary in an BoundaryPair instance.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

property axis_coord: float

value of the coordinate that defines this boundary condition

Type:

float

check_value_rank(rank)

Check whether the values at the boundaries have the correct rank.

Parameters:

rank (int) – The tensorial rank of the field for this boundary condition

Return type:

None

Throws:

RuntimeError: if the value does not have rank rank

copy(upper=None, rank=None)

Parameters:

• self (TBC)

• upper (bool | None)

• rank (int | None)

Return type:

TBC

classmethod from_data(grid, axis, upper, data, *, rank=0)

Create boundary from some data.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Indicates whether this boundary condition is associated with the upper or lower side of the axis.

• data (str or dict) – Data that describes the boundary

• rank (int) – The tensorial rank of the field for this boundary condition

Returns:

the instance created from the data

Return type:

BCBase

Throws:

ValueError if data cannot be interpreted as a boundary condition

classmethod from_dict(grid, axis, upper, data, *, rank=0)

Create boundary from data given in dictionary.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Indicates whether this boundary condition is associated with the upper or lower side of the axis.

• data (dict) – The dictionary defining the boundary condition

• rank (int) – The tensorial rank of the field for this boundary condition

Return type:

BCBase

classmethod from_str(grid, axis, upper, condition, *, rank=0, **kwargs)

Creates boundary from a given string identifier.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Indicates whether this boundary condition is associated with the upper or lower side of the axis.

• condition (str) – Identifies the boundary condition

• rank (int) – The tensorial rank of the field for this boundary condition

• **kwargs – Additional arguments passed to the constructor

Return type:

BCBase

classmethod get_help()

Return information on how boundary conditions can be set.

Return type:

str

get_mathematical_representation(field_name='C')

Return mathematical representation of the boundary condition.

Parameters:

field_name (str)

Return type:

str

get_sparse_matrix_data(idx)

Parameters:

idx (tuple[int, ...])

Return type:

tuple[float, dict[int, float]]

get_virtual_point(arr, idx=None)

Parameters:

idx (tuple[int, ...] | None)

Return type:

float

homogeneous: bool

determines whether the boundary condition depends on space

Type:

bool

make_adjacent_evaluator()

Returns a function evaluating the value adjacent to a given point.

Deprecated since version Since: 2023-12-19

Returns:

A function with signature (arr_1d, i_point, bc_idx), where arr_1d is the one-dimensional data array (the data points along the axis perpendicular to the boundary), i_point is the index into this array for the current point and bc_idx are the remaining indices of the current point, which indicate the location on the boundary plane. The result of the function is the data value at the adjacent point along the axis associated with this boundary condition in the upper (lower) direction when upper is True (False).

Return type:

function

make_ghost_cell_sender()

Return function that might mpi_send data to set ghost cells for this boundary.

Return type:

GhostCellSetter

make_ghost_cell_setter()

Return function that sets the ghost cells for this boundary.

Return type:

GhostCellSetter

abstract make_virtual_point_evaluator()

Returns a function evaluating the value at the virtual support point.

Returns:

A function that takes the data array and an index marking the current point, which is assumed to be a virtual point. The result is the data value at this point, which is calculated using the boundary condition.

Return type:

function

names: list[str]

identifiers used to specify the given boundary class

Type:

list

normal: bool = False

determines whether the boundary condition only affects normal components.

If this flag is False, boundary conditions must specify values for all components of the field. If True, only the normal components at the boundary are specified.

Type:

bool

property periodic: bool

whether the boundary condition is periodic

Type:

bool

abstract set_ghost_cells(data_full, *, args=None)

Set the ghost cell values for this boundary.

Parameters:

• data_full (ndarray) – The full field data including ghost points

• args (ndarray) – Determines what boundary conditions are set. args should be set to {TARGET: value}. Here, TARGET determines how the value is interpreted and what boundary condition is actually enforced: the value of the virtual points directly (virtual_point), the value of the field at the boundary (value) or the outward derivative of the field at the boundary (derivative).

Return type:

None

to_subgrid(subgrid)

Converts this boundary condition to one valid for a given subgrid.

Parameters:

• subgrid (GridBase) – Grid of the new boundary conditions

• self (TBC)

Returns:

Boundary conditions valid on the subgrid

Return type:

BCBase

exception BCDataError

Bases: ValueError

Exception that signals that incompatible data was supplied for the BC.

class ConstBC1stOrderBase(grid, axis, upper, *, rank=0, value=0)

Bases: ConstBCBase

Represents a single boundary in an BoundaryPair instance.

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur. However, the function is safe when value cannot be an arbitrary string.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• normal (bool) – Flag indicating whether the condition is only applied in the normal direction.

• value (float or str or ndarray) – a value stored with the boundary condition. The interpretation of this value depends on the type of boundary condition. If value is a single value (or tensor in case of tensorial boundary conditions), the same value is applied to all points. Inhomogeneous boundary conditions are possible by supplying an expression as a string, which then may depend on the axes names of the respective grid.

get_sparse_matrix_data(idx)

Sets the elements of the sparse representation of this condition.

Parameters:

idx (tuple) – The index of the point that must lie on the boundary condition

Returns:

A constant value and a dictionary with indices and factors that can be used to calculate this virtual point

Return type:

float, dict

get_virtual_point(arr, idx=None)

Calculate the value of the virtual point outside the boundary.

Parameters:

• arr (array) – The data values associated with the grid

• idx (tuple) – The index of the point to evaluate. This is a tuple of length grid.num_axes with the either -1 or dim as the entry for the axis associated with this boundary condition. Here, dim is the dimension of the axis. The index is optional if dim == 1.

Returns:

Value at the virtual support point

Return type:

float

abstract get_virtual_point_data(compiled=False)

Return data suitable for calculating virtual points.

Parameters:

compiled (bool) – Flag indicating whether a compiled version is required, which automatically takes updated values into account when it is used in numba-compiled code.

Returns:

the data structure associated with this virtual point

Return type:

tuple

make_adjacent_evaluator()

Returns a function evaluating the value adjacent to a given point.

Deprecated since version Since: 2023-12-19

Returns:

A function with signature (arr_1d, i_point, bc_idx), where arr_1d is the one-dimensional data array (the data points along the axis perpendicular to the boundary), i_point is the index into this array for the current point and bc_idx are the remaining indices of the current point, which indicate the location on the boundary plane. The result of the function is the data value at the adjacent point along the axis associated with this boundary condition in the upper (lower) direction when upper is True (False).

Return type:

function

make_virtual_point_evaluator()

Returns a function evaluating the value at the virtual support point.

Returns:

A function that takes the data array and an index marking the current point, which is assumed to be a virtual point. The result is the data value at this point, which is calculated using the boundary condition.

Return type:

function

set_ghost_cells(data_full, *, args=None)

Set the ghost cell values for this boundary.

Parameters:

• data_full (ndarray) – The full field data including ghost points

• args (ndarray) – Determines what boundary conditions are set. args should be set to {TARGET: value}. Here, TARGET determines how the value is interpreted and what boundary condition is actually enforced: the value of the virtual points directly (virtual_point), the value of the field at the boundary (value) or the outward derivative of the field at the boundary (derivative).

Return type:

None

class ConstBC2ndOrderBase(grid, axis, upper, *, rank=0, value=0)

Bases: ConstBCBase

Abstract base class for boundary conditions of 2nd order.

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur. However, the function is safe when value cannot be an arbitrary string.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• normal (bool) – Flag indicating whether the condition is only applied in the normal direction.

• value (float or str or ndarray) – a value stored with the boundary condition. The interpretation of this value depends on the type of boundary condition. If value is a single value (or tensor in case of tensorial boundary conditions), the same value is applied to all points. Inhomogeneous boundary conditions are possible by supplying an expression as a string, which then may depend on the axes names of the respective grid.

get_sparse_matrix_data(idx)

Sets the elements of the sparse representation of this condition.

Parameters:

idx (tuple) – The index of the point that must lie on the boundary condition

Returns:

A constant value and a dictionary with indices and factors that can be used to calculate this virtual point

Return type:

float, dict

get_virtual_point(arr, idx=None)

Calculate the value of the virtual point outside the boundary.

Parameters:

• arr (array) – The data values associated with the grid

• idx (tuple) – The index of the point to evaluate. This is a tuple of length grid.num_axes with the either -1 or dim as the entry for the axis associated with this boundary condition. Here, dim is the dimension of the axis. The index is optional if dim == 1.

Returns:

Value at the virtual support point

Return type:

float

abstract get_virtual_point_data()

Return data suitable for calculating virtual points.

Returns:

the data structure associated with this virtual point

Return type:

tuple

make_adjacent_evaluator()

Returns a function evaluating the value adjacent to a given point.

Deprecated since version Since: 2023-12-19

Returns:

A function with signature (arr_1d, i_point, bc_idx), where arr_1d is the one-dimensional data array (the data points along the axis perpendicular to the boundary), i_point is the index into this array for the current point and bc_idx are the remaining indices of the current point, which indicate the location on the boundary plane. The result of the function is the data value at the adjacent point along the axis associated with this boundary condition in the upper (lower) direction when upper is True (False).

Return type:

function

make_virtual_point_evaluator()

Returns a function evaluating the value at the virtual support point.

Returns:

A function that takes the data array and an index marking the current point, which is assumed to be a virtual point. The result is the data value at this point, which is calculated using the boundary condition.

Return type:

function

set_ghost_cells(data_full, *, args=None)

Set the ghost cell values for this boundary.

Parameters:

• data_full (ndarray) – The full field data including ghost points

• args (ndarray) – Determines what boundary conditions are set. args should be set to {TARGET: value}. Here, TARGET determines how the value is interpreted and what boundary condition is actually enforced: the value of the virtual points directly (virtual_point), the value of the field at the boundary (value) or the outward derivative of the field at the boundary (derivative).

Return type:

None

class ConstBCBase(grid, axis, upper, *, rank=0, value=0)

Bases: BCBase

Base class representing a boundary whose virtual point is set from constants.

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur. However, the function is safe when value cannot be an arbitrary string.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• normal (bool) – Flag indicating whether the condition is only applied in the normal direction.

• value (float or str or ndarray) – a value stored with the boundary condition. The interpretation of this value depends on the type of boundary condition. If value is a single value (or tensor in case of tensorial boundary conditions), the same value is applied to all points. Inhomogeneous boundary conditions are possible by supplying an expression as a string, which then may depend on the axes names of the respective grid.

copy(upper=None, rank=None, value=None)

Return a copy of itself, but with a reference to the same grid.

Parameters:

• self (ConstBCBase)

• upper (bool | None)

• rank (int | None)

• value (float | ndarray | str | None)

Return type:

ConstBCBase

link_value(value)

Link value of this boundary condition to external array.

Parameters:

value (ndarray)

to_subgrid(subgrid)

Converts this boundary condition to one valid for a given subgrid.

Parameters:

• subgrid (GridBase) – Grid of the new boundary conditions

• self (ConstBCBase)

Returns:

Boundary conditions valid on the subgrid

Return type:

ConstBCBase

property value: ndarray

value_is_linked: bool

flag that indicates whether the value associated with this boundary condition is linked to ndarray managed by external code.

Type:

bool

class CurvatureBC(grid, axis, upper, *, rank=0, value=0)

Bases: ConstBC2ndOrderBase

Represents a boundary condition imposing the 2nd normal derivative at the boundary.

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur. However, the function is safe when value cannot be an arbitrary string.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• normal (bool) – Flag indicating whether the condition is only applied in the normal direction.

• value (float or str or ndarray) – a value stored with the boundary condition. The interpretation of this value depends on the type of boundary condition. If value is a single value (or tensor in case of tensorial boundary conditions), the same value is applied to all points. Inhomogeneous boundary conditions are possible by supplying an expression as a string, which then may depend on the axes names of the respective grid.

get_mathematical_representation(field_name='C')

Return mathematical representation of the boundary condition.

Parameters:

field_name (str)

Return type:

str

get_virtual_point_data()

Return data suitable for calculating virtual points.

Returns:

the data structure associated with this virtual point

Return type:

tuple

names: list[str] = ['curvature', 'second_derivative', 'extrapolate']

identifiers used to specify the given boundary class

Type:

list

class DirichletBC(grid, axis, upper, *, rank=0, value=0)

Bases: ConstBC1stOrderBase

Represents a boundary condition imposing the value.

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur. However, the function is safe when value cannot be an arbitrary string.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• normal (bool) – Flag indicating whether the condition is only applied in the normal direction.

• value (float or str or ndarray) – a value stored with the boundary condition. The interpretation of this value depends on the type of boundary condition. If value is a single value (or tensor in case of tensorial boundary conditions), the same value is applied to all points. Inhomogeneous boundary conditions are possible by supplying an expression as a string, which then may depend on the axes names of the respective grid.

get_mathematical_representation(field_name='C')

Return mathematical representation of the boundary condition.

Parameters:

field_name (str)

Return type:

str

get_virtual_point_data(compiled=False)

Return data suitable for calculating virtual points.

Parameters:

compiled (bool) – Flag indicating whether a compiled version is required, which automatically takes updated values into account when it is used in numba-compiled code.

Returns:

the data structure associated with this virtual point

Return type:

tuple

names: list[str] = ['value', 'dirichlet']

identifiers used to specify the given boundary class

Type:

list

class ExpressionBC(grid, axis, upper, *, rank=0, value=0, const=0, target='virtual_point', user_funcs=None, value_cell=None)

Bases: BCBase

Represents a boundary whose virtual point is calculated from an expression.

The expression is given as a string and will be parsed by sympy or a function that is optionally compiled with numba. The expression can contain typical mathematical operators and may depend on the value at the last support point next to the boundary (value), spatial coordinates defined by the grid marking the boundary point (e.g., x or r), and time t.

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• value (float or str or callable) – An expression that determines the value of the boundary condition. Alternatively, this can be a function with signature (value, dx, *coords, t) that determines the value of target from the field value value (the value of the adjacent cell unless value_cell is specified), the spatial discretization dx in the direction perpendicular to the wall, the spatial coordinates of the wall point, and time t. Ideally, this function should be numba-compilable since simulations might otherwise be very slow.

• const (float or str or callable) – An expression similar to value, which is only used for mixed (Robin) boundary conditions. Note that the implementation currently does not support that one argument is given as a callable function while the other is defined via an expression, so both need to have the same type.

• target (str) – Selects which value is actually set. Possible choices include value, derivative, mixed, and virtual_point.

• user_funcs (dict, optional) – A dictionary with user defined functions that can be used in expressions

• value_cell (int) – Determines which cells is read to determine the field value that is used as value in the expression or the function call. The default (None) specifies the adjacent cell.

copy(upper=None, rank=None)

Return a copy of itself, but with a reference to the same grid.

Parameters:

• self (ExpressionBC)

• upper (bool | None)

• rank (int | None)

Return type:

ExpressionBC

get_mathematical_representation(field_name='C')

Return mathematical representation of the boundary condition.

Parameters:

field_name (str)

Return type:

str

get_sparse_matrix_data(idx)

Parameters:

idx (tuple[int, ...])

Return type:

tuple[float, dict[int, float]]

get_virtual_point(arr, idx=None)

Parameters:

idx (tuple[int, ...] | None)

Return type:

float

make_adjacent_evaluator()

Returns a function evaluating the value adjacent to a given point.

Deprecated since version Since: 2023-12-19

Returns:

A function with signature (arr_1d, i_point, bc_idx), where arr_1d is the one-dimensional data array (the data points along the axis perpendicular to the boundary), i_point is the index into this array for the current point and bc_idx are the remaining indices of the current point, which indicate the location on the boundary plane. The result of the function is the data value at the adjacent point along the axis associated with this boundary condition in the upper (lower) direction when upper is True (False).

Return type:

function

make_virtual_point_evaluator()

Returns a function evaluating the value at the virtual support point.

Returns:

A function that takes the data array and an index marking the current point, which is assumed to be a virtual point. The result is the data value at this point, which is calculated using the boundary condition.

Return type:

function

names: list[str] = ['virtual_point']

identifiers used to specify the given boundary class

Type:

list

set_ghost_cells(data_full, *, args=None)

Set the ghost cell values for this boundary.

Parameters:

• data_full (ndarray) – The full field data including ghost points

• args (ndarray) – Determines what boundary conditions are set. args should be set to {TARGET: value}. Here, TARGET determines how the value is interpreted and what boundary condition is actually enforced: the value of the virtual points directly (virtual_point), the value of the field at the boundary (value) or the outward derivative of the field at the boundary (derivative).

Return type:

None

to_subgrid(subgrid)

Converts this boundary condition to one valid for a given subgrid.

Parameters:

• subgrid (GridBase) – Grid of the new boundary conditions

• self (ExpressionBC)

Returns:

Boundary conditions valid on the subgrid

Return type:

BCBase

class ExpressionDerivativeBC(grid, axis, upper, *, rank=0, value=0, target='derivative', user_funcs=None, value_cell=None)

Bases: ExpressionBC

Represents a boundary whose outward derivative is calculated from an expression.

The expression is given as a string and will be parsed by sympy. The expression can contain typical mathematical operators and may depend on the value at the last support point next to the boundary (value), spatial coordinates defined by the grid marking the boundary point (e.g., x or r), and time t.

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• value (float or str or callable) – An expression that determines the value of the boundary condition. Alternatively, this can be a function with signature (value, dx, *coords, t) that determines the value of target from the field value value (the value of the adjacent cell unless value_cell is specified), the spatial discretization dx in the direction perpendicular to the wall, the spatial coordinates of the wall point, and time t. Ideally, this function should be numba-compilable since simulations might otherwise be very slow.

• const (float or str or callable) – An expression similar to value, which is only used for mixed (Robin) boundary conditions. Note that the implementation currently does not support that one argument is given as a callable function while the other is defined via an expression, so both need to have the same type.

• target (str) – Selects which value is actually set. Possible choices include value, derivative, mixed, and virtual_point.

• user_funcs (dict, optional) – A dictionary with user defined functions that can be used in expressions

• value_cell (int) – Determines which cells is read to determine the field value that is used as value in the expression or the function call. The default (None) specifies the adjacent cell.

names: list[str] = ['derivative_expression', 'derivative_expr']

identifiers used to specify the given boundary class

Type:

list

class ExpressionMixedBC(grid, axis, upper, *, rank=0, value=0, const=0, target='mixed', user_funcs=None, value_cell=None)

Bases: ExpressionBC

Represents a boundary whose outward derivative is calculated from an expression.

The expression is given as a string and will be parsed by sympy. The expression can contain typical mathematical operators and may depend on the value at the last support point next to the boundary (value), spatial coordinates defined by the grid marking the boundary point (e.g., x or r), and time t.

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• value (float or str or callable) – An expression that determines the value of the boundary condition. Alternatively, this can be a function with signature (value, dx, *coords, t) that determines the value of target from the field value value (the value of the adjacent cell unless value_cell is specified), the spatial discretization dx in the direction perpendicular to the wall, the spatial coordinates of the wall point, and time t. Ideally, this function should be numba-compilable since simulations might otherwise be very slow.

• const (float or str or callable) – An expression similar to value, which is only used for mixed (Robin) boundary conditions. Note that the implementation currently does not support that one argument is given as a callable function while the other is defined via an expression, so both need to have the same type.

• target (str) – Selects which value is actually set. Possible choices include value, derivative, mixed, and virtual_point.

• user_funcs (dict, optional) – A dictionary with user defined functions that can be used in expressions

• value_cell (int) – Determines which cells is read to determine the field value that is used as value in the expression or the function call. The default (None) specifies the adjacent cell.

names: list[str] = ['mixed_expression', 'mixed_expr', 'robin_expression', 'robin_expr']

identifiers used to specify the given boundary class

Type:

list

class ExpressionValueBC(grid, axis, upper, *, rank=0, value=0, target='value', user_funcs=None, value_cell=None)

Bases: ExpressionBC

Represents a boundary whose value is calculated from an expression.

The expression is given as a string and will be parsed by sympy. The expression can contain typical mathematical operators and may depend on the value at the last support point next to the boundary (value), spatial coordinates defined by the grid marking the boundary point (e.g., x or r), and time t.

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• value (float or str or callable) – An expression that determines the value of the boundary condition. Alternatively, this can be a function with signature (value, dx, *coords, t) that determines the value of target from the field value value (the value of the adjacent cell unless value_cell is specified), the spatial discretization dx in the direction perpendicular to the wall, the spatial coordinates of the wall point, and time t. Ideally, this function should be numba-compilable since simulations might otherwise be very slow.

• const (float or str or callable) – An expression similar to value, which is only used for mixed (Robin) boundary conditions. Note that the implementation currently does not support that one argument is given as a callable function while the other is defined via an expression, so both need to have the same type.

• target (str) – Selects which value is actually set. Possible choices include value, derivative, mixed, and virtual_point.

• user_funcs (dict, optional) – A dictionary with user defined functions that can be used in expressions

• value_cell (int) – Determines which cells is read to determine the field value that is used as value in the expression or the function call. The default (None) specifies the adjacent cell.

names: list[str] = ['value_expression', 'value_expr']

identifiers used to specify the given boundary class

Type:

list

class MixedBC(grid, axis, upper, *, rank=0, value=0, const=0)

Bases: ConstBC1stOrderBase

represents a mixed (or Robin) boundary condition imposing a derivative in the outward normal direction of the boundary that is given by an affine function involving the actual value:

\[\partial_n c + \gamma c = \beta\]

Here, \(c\) is the field to which the condition is applied, \(\gamma\) quantifies the influence of the field and \(\beta\) is the constant term. Note that \(\gamma = 0\) corresponds to Dirichlet conditions imposing \(\beta\) as the derivative. Conversely, \(\gamma \rightarrow \infty\) corresponds to imposing a zero value on \(c\).

This condition can be enforced by using one of the following variants

bc = {'mixed': VALUE}
bc = {'type': 'mixed', 'value': VALUE, 'const': CONST}

where VALUE corresponds to \(\gamma\) and CONST to \(\beta\).

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• value (float or str or array) – The parameter \(\gamma\) quantifying the influence of the field onto its normal derivative. If value is a single value (or tensor in case of tensorial boundary conditions), the same value is applied to all points. Inhomogeneous boundary conditions are possible by supplying an expression as a string, which then may depend on the axes names of the respective grid.

• const (float or ndarray or str) – The parameter \(\beta\) determining the constant term for the boundary condition. Supports the same input as value.

copy(upper=None, rank=None, value=None, const=None)

Return a copy of itself, but with a reference to the same grid.

Parameters:

• self (MixedBC)

• upper (bool | None)

• rank (int | None)

• value (float | ndarray | str | None)

• const (float | ndarray | str | None)

Return type:

MixedBC

get_mathematical_representation(field_name='C')

Return mathematical representation of the boundary condition.

Parameters:

field_name (str)

Return type:

str

get_virtual_point_data(compiled=False)

Return data suitable for calculating virtual points.

Parameters:

compiled (bool) – Flag indicating whether a compiled version is required, which automatically takes updated values into account when it is used in numba-compiled code.

Returns:

the data structure associated with this virtual point

Return type:

tuple

names: list[str] = ['mixed', 'robin']

identifiers used to specify the given boundary class

Type:

list

to_subgrid(subgrid)

Converts this boundary condition to one valid for a given subgrid.

Parameters:

• subgrid (GridBase) – Grid of the new boundary conditions

• self (MixedBC)

Returns:

Boundary conditions valid on the subgrid

Return type:

ConstBCBase

class NeumannBC(grid, axis, upper, *, rank=0, value=0)

Bases: ConstBC1stOrderBase

Represents a boundary condition imposing the derivative in the outward normal direction of the boundary.

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur. However, the function is safe when value cannot be an arbitrary string.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• normal (bool) – Flag indicating whether the condition is only applied in the normal direction.

• value (float or str or ndarray) – a value stored with the boundary condition. The interpretation of this value depends on the type of boundary condition. If value is a single value (or tensor in case of tensorial boundary conditions), the same value is applied to all points. Inhomogeneous boundary conditions are possible by supplying an expression as a string, which then may depend on the axes names of the respective grid.

get_mathematical_representation(field_name='C')

Return mathematical representation of the boundary condition.

Parameters:

field_name (str)

Return type:

str

get_virtual_point_data(compiled=False)

Return data suitable for calculating virtual points.

Parameters:

compiled (bool) – Flag indicating whether a compiled version is required, which automatically takes updated values into account when it is used in numba-compiled code.

Returns:

the data structure associated with this virtual point

Return type:

tuple

names: list[str] = ['derivative', 'neumann']

identifiers used to specify the given boundary class

Type:

list

class NormalCurvatureBC(grid, axis, upper, *, rank=0, value=0)

Bases: CurvatureBC

Represents a boundary condition imposing the 2nd normal derivative onto the normal components at the boundary.

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur. However, the function is safe when value cannot be an arbitrary string.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• normal (bool) – Flag indicating whether the condition is only applied in the normal direction.

• value (float or str or ndarray) – a value stored with the boundary condition. The interpretation of this value depends on the type of boundary condition. If value is a single value (or tensor in case of tensorial boundary conditions), the same value is applied to all points. Inhomogeneous boundary conditions are possible by supplying an expression as a string, which then may depend on the axes names of the respective grid.

names: list[str] = ['normal_curvature']

identifiers used to specify the given boundary class

Type:

list

normal: bool = True

determines whether the boundary condition only affects normal components.

If this flag is False, boundary conditions must specify values for all components of the field. If True, only the normal components at the boundary are specified.

Type:

bool

class NormalDirichletBC(grid, axis, upper, *, rank=0, value=0)

Bases: DirichletBC

Represents a boundary condition imposing the value on normal components.

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur. However, the function is safe when value cannot be an arbitrary string.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• normal (bool) – Flag indicating whether the condition is only applied in the normal direction.

• value (float or str or ndarray) – a value stored with the boundary condition. The interpretation of this value depends on the type of boundary condition. If value is a single value (or tensor in case of tensorial boundary conditions), the same value is applied to all points. Inhomogeneous boundary conditions are possible by supplying an expression as a string, which then may depend on the axes names of the respective grid.

names: list[str] = ['normal_value', 'normal_dirichlet', 'dirichlet_normal']

identifiers used to specify the given boundary class

Type:

list

normal: bool = True

determines whether the boundary condition only affects normal components.

If this flag is False, boundary conditions must specify values for all components of the field. If True, only the normal components at the boundary are specified.

Type:

bool

class NormalMixedBC(grid, axis, upper, *, rank=0, value=0, const=0)

Bases: MixedBC

represents a mixed (or Robin) boundary condition setting the derivative of the normal components in the outward normal direction of the boundary using an affine function involving the actual value:

\[\partial_n c + \gamma c = \beta\]

Here, \(c\) is the field to which the condition is applied, \(\gamma\) quantifies the influence of the field and \(\beta\) is the constant term. Note that \(\gamma = 0\) corresponds to Dirichlet conditions imposing \(\beta\) as the derivative. Conversely, \(\gamma \rightarrow \infty\) corresponds to imposing a zero value on \(c\).

This condition can be enforced by using one of the following variants

bc = {'mixed': VALUE}
bc = {'type': 'mixed', 'value': VALUE, 'const': CONST}

where VALUE corresponds to \(\gamma\) and CONST to \(\beta\).

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• value (float or str or array) – The parameter \(\gamma\) quantifying the influence of the field onto its normal derivative. If value is a single value (or tensor in case of tensorial boundary conditions), the same value is applied to all points. Inhomogeneous boundary conditions are possible by supplying an expression as a string, which then may depend on the axes names of the respective grid.

• const (float or ndarray or str) – The parameter \(\beta\) determining the constant term for the boundary condition. Supports the same input as value.

names: list[str] = ['normal_mixed', 'normal_robin']

identifiers used to specify the given boundary class

Type:

list

normal: bool = True

determines whether the boundary condition only affects normal components.

If this flag is False, boundary conditions must specify values for all components of the field. If True, only the normal components at the boundary are specified.

Type:

bool

class NormalNeumannBC(grid, axis, upper, *, rank=0, value=0)

Bases: NeumannBC

Represents a boundary condition imposing the derivative of normal components in the outward normal direction of the boundary.

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur. However, the function is safe when value cannot be an arbitrary string.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

• normal (bool) – Flag indicating whether the condition is only applied in the normal direction.

• value (float or str or ndarray) – a value stored with the boundary condition. The interpretation of this value depends on the type of boundary condition. If value is a single value (or tensor in case of tensorial boundary conditions), the same value is applied to all points. Inhomogeneous boundary conditions are possible by supplying an expression as a string, which then may depend on the axes names of the respective grid.

names: list[str] = ['normal_derivative', 'normal_neumann', 'neumann_normal']

identifiers used to specify the given boundary class

Type:

list

normal: bool = True

determines whether the boundary condition only affects normal components.

If this flag is False, boundary conditions must specify values for all components of the field. If True, only the normal components at the boundary are specified.

Type:

bool

class UserBC(grid, axis, upper, *, rank=0)

Bases: BCBase

Represents a boundary whose virtual point are set by the user.

Boundary conditions will only be set when a dictionary {TARGET: value} is supplied as argument args to set_ghost_cells() or the numba equivalent. Here, TARGET determines how the value is interpreted and what boundary condition is actually enforced: the value of the virtual points directly (virtual_point), the value of the field at the boundary (value) or the outward derivative of the field at the boundary (derivative).

Warning

This implies that the boundary conditions are never enforced automatically, e.g., when evaluating an operator. It is thus the user’s responsibility to ensure virtual points are set correctly before operators are applied.

Parameters:

• grid (GridBase) – The grid for which the boundary conditions are defined

• axis (int) – The axis to which this boundary condition is associated

• upper (bool) – Flag indicating whether this boundary condition is associated with the upper side of an axis or not. In essence, this determines the direction of the local normal vector of the boundary.

• rank (int) – The tensorial rank of the field for this boundary condition

copy(upper=None, rank=None)

Return a copy of itself, but with a reference to the same grid.

Parameters:

• self (TBC)

• upper (bool | None)

• rank (int | None)

Return type:

TBC

get_mathematical_representation(field_name='C')

Return mathematical representation of the boundary condition.

Parameters:

field_name (str)

Return type:

str

make_ghost_cell_setter()

Return function that sets the ghost cells for this boundary.

Return type:

GhostCellSetter

make_virtual_point_evaluator()

Returns a function evaluating the value at the virtual support point.

Returns:

A function that takes the data array and an index marking the current point, which is assumed to be a virtual point. The result is the data value at this point, which is calculated using the boundary condition.

Return type:

function

names: list[str] = ['user']

identifiers used to specify the given boundary class

Type:

list

set_ghost_cells(data_full, *, args=None)

Set the ghost cell values for this boundary.

Parameters:

• data_full (ndarray) – The full field data including ghost points

• args (ndarray) – Determines what boundary conditions are set. args should be set to {TARGET: value}. Here, TARGET determines how the value is interpreted and what boundary condition is actually enforced: the value of the virtual points directly (virtual_point), the value of the field at the boundary (value) or the outward derivative of the field at the boundary (derivative).

Return type:

None

to_subgrid(subgrid)

Converts this boundary condition to one valid for a given subgrid.

Parameters:

• subgrid (GridBase) – Grid of the new boundary conditions

• self (TBC)

Returns:

Boundary conditions valid on the subgrid

Return type:

BCBase

registered_boundary_condition_classes()

Returns all boundary condition classes that are currently defined.

Returns:

a dictionary with the names of the boundary condition classes

Return type:

dict

registered_boundary_condition_names()

Returns all named boundary conditions that are currently defined.

Returns:

a dictionary with the names of the boundary conditions that can be used

Return type:

dict