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
NeumannBC: Imposing the derivative of a field in the outward normal direction at the boundary based on a mathematical expression
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.

class BCBase(grid, axis, upper, *, rank=0)[source]¶

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)[source]¶

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)[source]¶

Parameters

self (TBC) –
upper (Optional[bool]) –
rank (Optional[int]) –

Return type

TBC

classmethod from_data(grid, axis, upper, data, *, rank=0)[source]¶

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)[source]¶

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)[source]¶

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

get_data(idx)[source]¶

Parameters: idx (Tuple[int, ...]) –
Return type: Tuple[float, Dict[int, float]]

classmethod get_help()[source]¶

Return information on how boundary conditions can be set

Return type: str

get_mathematical_representation(field_name='C')[source]¶

return mathematical representation of the boundary condition

Parameters: field_name (str) –
Return type: str

get_virtual_point(arr, idx=None)[source]¶

Parameters: idx (Optional[Tuple[int, ...]]) –
Return type: float

homogeneous: bool¶

determines whether the boundary condition depends on space

Type: bool

make_adjacent_evaluator()[source]¶

Return type: AdjacentEvaluator

make_ghost_cell_sender()[source]¶

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

Return type: GhostCellSetter

make_ghost_cell_setter()[source]¶

return function that sets the ghost cells for this boundary

Return type: GhostCellSetter

abstract make_virtual_point_evaluator()[source]¶

Return type: VirtualPointEvaluator

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)[source]¶

set the ghost cell values for this boundary

Parameters: data_full (ndarray) –
Return type: None

to_subgrid(subgrid)[source]¶

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[source]¶

Bases: ValueError

exception that signals that incompatible data was supplied for the BC

class ConstBC1stOrderBase(grid, axis, upper, *, rank=0, value=0)[source]¶

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_data(idx)[source]¶

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)[source]¶

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)[source]¶

Parameters: compiled (bool) –
Return type: Tuple[Any, Any, int]

make_adjacent_evaluator()[source]¶

returns a function evaluating the value adjacent to a given point

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()[source]¶

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)[source]¶

set the ghost cell values for this boundary

Parameters

data_full (ndarray) – The full field data including ghost points
args – Additional arguments that might be supported by special boundary conditions.

Return type

None

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 ConstBC2ndOrderBase(grid, axis, upper, *, rank=0, value=0)[source]¶

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_data(idx)[source]¶

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)[source]¶

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()[source]¶

return data suitable for calculating virtual points

Returns: the data associated with this virtual point
Return type: tuple

make_adjacent_evaluator()[source]¶

returns a function evaluating the value adjacent to a given point

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()[source]¶

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)[source]¶

set the ghost cell values for this boundary

Parameters

data_full (ndarray) – The full field data including ghost points
args – Additional arguments that might be supported by special boundary conditions.

Return type

None

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 ConstBCBase(grid, axis, upper, *, rank=0, value=0)[source]¶

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)[source]¶

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

Parameters

self (ConstBCBase) –
upper (Optional[bool]) –
rank (Optional[int]) –
value (Optional[Union[float, ndarray, str]]) –

Return type

ConstBCBase

link_value(value)[source]¶

link value of this boundary condition to external array

Parameters: value (ndarray) –

to_subgrid(subgrid)[source]¶

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)[source]¶

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')[source]¶

return mathematical representation of the boundary condition

Parameters: field_name (str) –
Return type: str

get_virtual_point_data()[source]¶

return data suitable for calculating virtual points

Returns: the data structure associated with this virtual point
Return type: tuple

homogeneous: bool¶

determines whether the boundary condition depends on space

Type: bool

names: List[str] = ['curvature', 'second_derivative', 'extrapolate']¶

identifiers used to specify the given boundary class

Type: list

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 DirichletBC(grid, axis, upper, *, rank=0, value=0)[source]¶

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')[source]¶

return mathematical representation of the boundary condition

Parameters: field_name (str) –
Return type: str

get_virtual_point_data(compiled=False)[source]¶

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: BC1stOrderData

homogeneous: bool¶

determines whether the boundary condition depends on space

Type: bool

names: List[str] = ['value', 'dirichlet']¶

identifiers used to specify the given boundary class

Type: list

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 ExpressionBC(grid, axis, upper, *, rank=0, value=0, target='virtual_point')[source]¶

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. 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) – An expression that determines the value of the boundary condition.
target (str) – Selects which value is actually set. Possible choices include value, derivative, and virtual_point.

copy(upper=None, rank=None)[source]¶

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

Parameters

self (ExpressionBC) –
upper (Optional[bool]) –
rank (Optional[int]) –

Return type

ExpressionBC

get_data(idx)[source]¶

Parameters: idx (Tuple[int, ...]) –
Return type: Tuple[float, Dict[int, float]]

get_mathematical_representation(field_name='C')[source]¶

return mathematical representation of the boundary condition

Parameters: field_name (str) –
Return type: str

get_virtual_point(arr, idx=None)[source]¶

Parameters: idx (Optional[Tuple[int, ...]]) –
Return type: float

homogeneous: bool¶

determines whether the boundary condition depends on space

Type: bool

make_adjacent_evaluator()[source]¶

Return type: AdjacentEvaluator

make_virtual_point_evaluator()[source]¶

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)[source]¶

set the ghost cell values for this boundary

Parameters

data_full (ndarray) – The full field data including ghost points
args – Additional arguments that might be supported by special boundary conditions.

Return type

None

to_subgrid(subgrid)[source]¶

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')[source]¶

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) – An expression that determines the value of the boundary condition.
target (str) – Selects which value is actually set. Possible choices include value, derivative, and virtual_point.

homogeneous: bool¶

determines whether the boundary condition depends on space

Type: bool

names: List[str] = ['derivative_expression', 'derivative_expr']¶

identifiers used to specify the given boundary class

Type: list

class ExpressionValueBC(grid, axis, upper, *, rank=0, value=0, target='value')[source]¶

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) – An expression that determines the value of the boundary condition.
target (str) – Selects which value is actually set. Possible choices include value, derivative, and virtual_point.

homogeneous: bool¶

determines whether the boundary condition depends on space

Type: bool

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)[source]¶

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)[source]¶

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

Parameters

self (MixedBC) –
upper (Optional[bool]) –
rank (Optional[int]) –
value (Optional[Union[float, ndarray, str]]) –
const (Optional[Union[float, ndarray, str]]) –

Return type

MixedBC

get_mathematical_representation(field_name='C')[source]¶

return mathematical representation of the boundary condition

Parameters: field_name (str) –
Return type: str

get_virtual_point_data(compiled=False)[source]¶

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: BC1stOrderData

homogeneous: bool¶

determines whether the boundary condition depends on space

Type: bool

names: List[str] = ['mixed', 'robin']¶

identifiers used to specify the given boundary class

Type: list

to_subgrid(subgrid)[source]¶

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

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 NeumannBC(grid, axis, upper, *, rank=0, value=0)[source]¶

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')[source]¶

return mathematical representation of the boundary condition

Parameters: field_name (str) –
Return type: str

get_virtual_point_data(compiled=False)[source]¶

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: BC1stOrderData

homogeneous: bool¶

determines whether the boundary condition depends on space

Type: bool

names: List[str] = ['derivative', 'neumann']¶

identifiers used to specify the given boundary class

Type: list

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 NormalCurvatureBC(grid, axis, upper, *, rank=0, value=0)[source]¶

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.

homogeneous: bool¶

determines whether the boundary condition depends on space

Type: bool

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

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 NormalDirichletBC(grid, axis, upper, *, rank=0, value=0)[source]¶

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.

homogeneous: bool¶

determines whether the boundary condition depends on space

Type: bool

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

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 NormalMixedBC(grid, axis, upper, *, rank=0, value=0, const=0)[source]¶

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.

homogeneous: bool¶

determines whether the boundary condition depends on space

Type: bool

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

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 NormalNeumannBC(grid, axis, upper, *, rank=0, value=0)[source]¶

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.

homogeneous: bool¶

determines whether the boundary condition depends on space

Type: bool

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

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 UserBC(grid, axis, upper, *, rank=0)[source]¶

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)[source]¶

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

Parameters

self (TBC) –
upper (Optional[bool]) –
rank (Optional[int]) –

Return type

TBC

get_mathematical_representation(field_name='C')[source]¶

return mathematical representation of the boundary condition

Parameters: field_name (str) –
Return type: str

homogeneous: bool¶

determines whether the boundary condition depends on space

Type: bool

make_ghost_cell_setter()[source]¶

return function that sets the ghost cells for this boundary

Return type: GhostCellSetter

make_virtual_point_evaluator()[source]¶

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)[source]¶

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)[source]¶

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()[source]¶

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()[source]¶

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