emulsim.elements.fields module

Provides elements that represent extended, discretized fields.

`MeanfieldElement`	Element representing a homogeneous, changing field.
`ReservoirElement`	Element representing a homogeneous, constant field.
`ScalarFieldElement`	Element representing a scalar spatially-resolved field.
`FieldCollectionElement`	Element representing multiple spatially-resolved fields.
`ScalarBoundaryFieldElement`	Element representing the scalar field of a boundary of a field.

class FieldCollectionElement(data: ndarray | None = None, parameters: dict[str, Any] | None = None)[source]

Bases: ArrayElementBase

Element representing multiple spatially-resolved fields.

Parameters Dictionary:

grid: The grid on which the fields are discretized (default=None)
label: The name of the field collection (default=’’)
plot_args: Extra arguments for plotting this element (default={})

Parameters:

data – The data describing the state
parameters – Additional parameters that affect the element

Parameters of FieldCollectionElement:

plot_args: Extra arguments for plotting this element (Default value: {})
grid: The grid on which the fields are discretized. The grid also determines the space dimension and its extension. (Default value: None)
label: The name of the field collection (Default value: '')

add_amounts(point: ndarray, amounts: ndarray)[source]

Add the given amounts to the fields.

Parameters:

point (ndarray) – Point where the amounts are added to the fields
amounts (ndarray) – The total amount added to each field

property amounts: ndarray

the total material amount in each field.

Type:: ndarray

copy(method: Literal['clean', 'shallow', 'data'], data=None)[source]

Create a copy of the state.

Parameters:

method (str) – Determines whether a clean, shallow, or data copy is performed. See copy() for details.
data – Data to be used instead of the one in the current state. This data is used as is and not copied!

Returns:

A copy of the current state object

property data: ndarray

Value at the valid grid points of all fields.

Type:: ndarray

property degrees_of_freedom: int

the number of degrees of freedom for this element

Type:: int

property field: FieldCollection

all fields.

Type:: FieldCollection

classmethod from_fields(fields: FieldCollection) → FieldCollectionElement[source]

Create a scalar field element from a scalar field.

Parameters:: field (FieldCollection) – The field collection that initializes the element
Returns:: The initialized instance
Return type:: FieldCollectionElement

get_concentrations(points: ndarray)[source]

Determine concentrations at the given points.

Parameters:: points (ndarray) – The coordinates of the single point or the list of points at which the concentrations are returned

property grid: CartesianGrid

discretization grid.

Type:: CartesianGrid

make_add_amounts_compiled() → Callable[source]

Get a compiled function for adding amount to the field.

Returns:: a function with signature (data: ndarray, point: ndarray, amounts: ndarray), which adds amounts to the field state given by data at point point.
Return type:: callable

make_get_concentrations_compiled() → Callable[source]

Get a compiled function for obtaining concentrations.

Returns:: a function with signature (data: ndarray, point: ndarray), which determines the concentrations at point point given the field state data.
Return type:: callable

property num_fields: int

the number of fields described by this collection

Type:: int

parameters_default = [Parameter(name='grid', default_value=None, cls=<class 'object'>, description='The grid on which the fields are discretized. The grid also determines the space dimension and its extension.', choices=None, required=False, hidden=False, extra={'serializer': <function FieldCollectionElement.<lambda>>, 'unserializer': <bound method GridBase.from_state of <class 'pde.grids.base.GridBase'>>}), Parameter(name='label', default_value='', cls=<class 'str'>, description='The name of the field collection', choices=None, required=False, hidden=False, extra={})]

parameters (with default values) of this subclass

Type:: list

plot(ax=None, **kwargs)[source]

Plot the field.

Note that only the first field is plotted if the dimension is different from 1. The method simply calls plot() and all arguments are forwarded.

property total_amount: float

the total material amount in all fields combined

Type:: float

class FieldElementBase(data: ndarray | None = None, parameters: dict[str, Any] | None = None)[source]

Bases: ArrayElementBase

Base class for field elements.

Parameters Dictionary:

plot_args: Extra arguments for plotting this element (default={})

Parameters:

data – The data describing the state
parameters – Additional parameters that affect the element

Parameters of FieldElementBase:

plot_args: Extra arguments for plotting this element (Default value: {})

abstractmethod add_amount(point: ndarray, amount: float)[source]

Add the given amount to the field.

Parameters:

point (ndarray) – Point where the amount is added to the field
amount (float) – The total amount added to the field

property average_concentration: float

the average material concentration in the field

Type:: float

check_coupling_dim(dim: int) → None[source]

Checks the dimension of a coupled field.

Parameters:: dim (int) – The dimension of the element that needs to be coupled to this field
Raises:: DimensionError – if the dimensions are incompatible

abstractmethod get_concentration(points)[source]

Determine concentration at the given points.

Parameters:: points (ndarray) – The coordinates of the single point or the list of points at which the concentration is returned

abstract property grid: CartesianGrid

discretization grid.

Type:: pde.grids.cartesian.CartesianGrid

make_add_amount_compiled() → Callable[source]

Get a compiled function for adding amount to the field.

Returns:: a function with signature (data: ndarray, point: ndarray, amount: float), which adds amount to the field state given by data at point point.
Return type:: callable

make_get_concentration_compiled() → Callable[source]

Get a compiled function for obtaining concentrations.

Returns:: a function with signature (data: ndarray, point: ndarray), which determines the concentration at point point given the field state data.
Return type:: callable

plot(ax=None, **kwargs)[source]: Plot the field.

set_bounds(bounds: Sequence[tuple[float, float]]) → None[source]

Set the boundaries of the field.

Parameters:: bounds (sequence) – A sequence of tuples specifying the lower and upper bound for each axis. The number of entries sets the space dimension.

abstract property total_amount: float

the total material amount in the field

Type:: float

class MeanfieldElement(data: float = 0, parameters: dict[str, Any] | None = None)[source]

Bases: FieldElementBase

Element representing a homogeneous, changing field.

Parameters Dictionary:

bounds: Sets the size of the Cartesian space covered by this element (default=None)
plot_args: Extra arguments for plotting this element (default={})
volume: Volume of the element (default=-1.0)

Parameters:

data (float) – The initial concentration in the field
parameters (dict) – Additional parameters determining how the element behaves. Most importantly, the entry ‘bounds’ determines the box on which the field is defined.

Parameters of MeanfieldElement:

plot_args: Extra arguments for plotting this element (Default value: {})
bounds: Sets the size of the Cartesian space covered by this element. This should be a list of tuples, where each element denotes the lower and upper bounds of an axis. The number of elements then determines the dimension of the space (Default value: None)
volume: Volume of the element. If negative, the volume is determine from bounds (Default value: -1.0)

add_amount(point: ndarray, amount: float)[source]

Add the given amount to the field.

Parameters:

point – Not used and only retained to match the interface
amount – The total amount added to the field

check_coupling_dim(dim: int) → None[source]

Checks the dimension of a coupled field.

Parameters:: dim (int) – The dimension of the element that needs to be coupled to this field

property concentration: float

the concentration in the field

Type:: float

property degrees_of_freedom: int

the number of degrees of freedom for this element

Type:: int

property field: ScalarField

representation as a scalar field.

Type:: ScalarField

classmethod from_field(field: ScalarField, parameters: dict[str, Any] | None = None) → MeanfieldElement[source]

Create a mean field element from a scalar field.

Parameters:

field (ScalarField) – The scalar field that initializes the element
parameters (dict) – Additional parameters determining how the element behaves. Note that the entry ‘bounds’ will be overwritten by the data from field.

Returns:

The initialized instance

Return type:

MeanfieldElement

get_concentration(points: ndarray)[source]

Determine concentration at the given points.

Parameters:: points (ndarray) – The coordinates of the single point or the list of points at which the concentration is returned

grid

discretization grid.

Type:: pde.grids.cartesian.CartesianGrid

make_add_amount_compiled() → Callable[source]

Get a compiled function for adding amount to the field.

Returns:: a function with signature (data: ndarray, point: ndarray, amount: float), which adds amount to the field state given by data at point point.
Return type:: callable

make_get_concentration_compiled() → Callable[source]

Get a compiled function for obtaining concentrations.

Returns:: a function with signature (data: ndarray, point: ndarray), which determines the concentration at point point given the field state data.
Return type:: callable

parameters_default = [Parameter(name='bounds', default_value=None, cls=<class 'object'>, description='Sets the size of the Cartesian space covered by this element. This should be a list of tuples, where each element denotes the lower and upper bounds of an axis. The number of elements then determines the dimension of the space', choices=None, required=True, hidden=False, extra={}), Parameter(name='volume', default_value=-1, cls=<class 'float'>, description='Volume of the element. If negative, the volume is determine from `bounds`', choices=None, required=False, hidden=False, extra={})]

parameters (with default values) of this subclass

Type:: list

plot(color='tab:blue', *args, title: str | None = None, filename: str | None = None, action: Literal['auto', 'close', 'none', 'sca', 'show'] = 'auto', ax_style: dict[str, Any] | None = None, fig_style: dict[str, Any] | None = None, ax=None, **kwargs)[source]

Plot the field.

Parameters:

color – The color in which the field is shown. All matplotlib color specifications are allowed.
title (str) – Title of the plot. If omitted, the title might be chosen automatically.
filename (str, optional) – If given, the plot is written to the specified file.
action (str) – Decides what to do with the final figure. If the argument is set to show, matplotlib.pyplot.show() will be called to show the plot. If the value is auto or none, the figure will be created, but not necessarily shown. The value close closes the figure, after saving it to a file when filename is given.
ax_style (dict) – Dictionary with properties that will be changed on the axis after the plot has been drawn by calling matplotlib.pyplot.setp(). A special item i this dictionary is use_offset, which is flag that can be used to control whether offset are shown along the axes of the plot.
fig_style (dict) – Dictionary with properties that will be changed on the figure after the plot has been drawn by calling matplotlib.pyplot.setp(). For instance, using fig_style={‘dpi’: 200} increases the resolution of the figure.
ax (matplotlib.axes.Axes) – Figure axes to be used for plotting. The special value “create” creates a new figure, while “reuse” attempts to reuse an existing figure, which is the default.

property total_amount: float

the total material amount in the field

Type:: float

class ReservoirElement(data: float = 0, parameters: dict[str, Any] | None = None)[source]

Bases: ArrayElementBase

Element representing a homogeneous, constant field.

Parameters Dictionary:

plot_args: Extra arguments for plotting this element (default={})

Parameters:: data (float) – The concentration in the field

add_amount(point: ndarray, amount: float)[source]

Add the given amount to the field.

Parameters:

point – Not used and only retained to match the interface
amount – The total amount added to the field

property concentration: float

the concentration in the field

Type:: float

property degrees_of_freedom: int

the number of degrees of freedom for this element

Type:: int

dim = None

get_concentration(points: ndarray)[source]

Determine concentration at the given points.

Parameters:: points (ndarray) – The coordinates of the single point or the list of points at which the concentration is returned

make_add_amount_compiled() → Callable[source]

Get a compiled function for adding amount to the field.

Returns:: a function with signature (data: ndarray, point: ndarray, amount: float), which adds amount to the field state given by data at point point.
Return type:: callable

make_get_concentration_compiled() → Callable[source]

Get a compiled function for obtaining concentrations.

Returns:: a function with signature (data: ndarray, point: ndarray), which determines the concentration at point point given the field state data.
Return type:: callable

plot(color='tab:blue', *args, title: str | None = None, filename: str | None = None, action: Literal['auto', 'close', 'none', 'sca', 'show'] = 'auto', ax_style: dict[str, Any] | None = None, fig_style: dict[str, Any] | None = None, ax=None, **kwargs)[source]

Plot the field.

Parameters:

color – The color in which the field is shown. All matplotlib color specifications are allowed.
title (str) – Title of the plot. If omitted, the title might be chosen automatically.
filename (str, optional) – If given, the plot is written to the specified file.
action (str) – Decides what to do with the final figure. If the argument is set to show, matplotlib.pyplot.show() will be called to show the plot. If the value is auto or none, the figure will be created, but not necessarily shown. The value close closes the figure, after saving it to a file when filename is given.
ax_style (dict) – Dictionary with properties that will be changed on the axis after the plot has been drawn by calling matplotlib.pyplot.setp(). A special item i this dictionary is use_offset, which is flag that can be used to control whether offset are shown along the axes of the plot.
fig_style (dict) – Dictionary with properties that will be changed on the figure after the plot has been drawn by calling matplotlib.pyplot.setp(). For instance, using fig_style={‘dpi’: 200} increases the resolution of the figure.
ax (matplotlib.axes.Axes) – Figure axes to be used for plotting. The special value “create” creates a new figure, while “reuse” attempts to reuse an existing figure, which is the default.

Bases: ScalarFieldElement

Element representing the scalar field of a boundary of a field.

Note

The data described by this element are volume concentrations with units length**-dim, where dim is the dimension of the bulk (so the boundary has dimensions dim - 1). To convert the concentration in a particular cell into a total amount it has to be multiplied by the cell volume and the thickness of the boundary.

Parameters Dictionary:

axis: Axis along which the boundary is placed (default=-1)
axis_position: Position of the boundary along the axis (default=nan)
grid: The grid on which the field is discretized (default=None)
label: The name of the field (default=’’)
plot_args: Extra arguments for plotting this element (default={})
plot_thickness: Thickness used when plotting the boundary (default=1.0)
thickness: Thickness of the boundary, which affects calculations of total amounts and potentially boundary conditions (default=1.0)

Parameters:

data (ndarray or float, optional) – Field values at the support points of the grid
parameters (dict) – Additional parameters determining how the element behaves. Most importantly, the entry ‘grid’ determines the discretization grid on which this field is defined.

Parameters of ScalarBoundaryFieldElement:

plot_args: Extra arguments for plotting this element (Default value: {})
grid: The grid on which the field is discretized. The grid also determines the space dimension and its extension. (Default value: None)
label: The name of the field (Default value: '')
axis: Axis along which the boundary is placed (Default value: -1)
axis_position: Position of the boundary along the axis. If omitted, the boundary might not support some operations. (Default value: nan)
thickness: Thickness of the boundary, which affects calculations of total amounts and potentially boundary conditions (Default value: 1.0)
plot_thickness: Thickness used when plotting the boundary (Default value: 1.0)

add_amount(point: ndarray, amount: float)[source]

Add the given amount to the field.

Parameters:

point (ndarray) – Point where the amount is added to the field
amount (float) – The total amount added to the field

property axis: int

the axis of the full domain that this boundary is associated with

Type:: int

bulk_coordinates: ndarray all boundary points in the bulk coordinate system.

check_coupling_dim(dim: int) → None[source]

Checks the dimension of a coupled field.

Parameters:: dim (int) – The dimension of the element that needs to be coupled to this field
Raises:: DimensionError – if the dimensions are incompatible

Create a scalar boundary element using a grid describing the full domain.

Parameters:

grid (CartesianGrid) – The scalar field describing the full domain
axis (int) – The axis along which the boundary is initialized
upper (bool) – Specified whether the upper or lower boundary along the given axis is specified by this field.
data (ndarray or float, optional) – Field values at the support points of the grid
parameters (dict) – Additional parameters determining how the element behaves.

classmethod from_field(field: ScalarField, parameters: dict[str, Any] | None = None) → ScalarBoundaryFieldElement[source]

Create a scalar boundary element from a scalar field.

Parameters:

field (ScalarField) – The scalar field that initializes the element
parameters (dict) – Additional parameters determining how the element behaves.

Returns:

The initialized instance

Return type:

ScalarFieldElement

make_add_amount_compiled() → Callable[source]

Get a compiled function for adding amount to the field.

Returns:: a function with signature (data: ndarray, point: ndarray, amount: float), which adds amount to the field state given by data at point point.
Return type:: callable

parameters_default = [Parameter(name='grid', default_value=None, cls=<class 'object'>, description='The grid on which the field is discretized. The grid also determines the space dimension and its extension.', choices=None, required=False, hidden=False, extra={'serializer': <function ScalarBoundaryFieldElement.<lambda>>, 'unserializer': <bound method GridBase.from_state of <class 'pde.grids.base.GridBase'>>}), Parameter(name='axis', default_value=-1, cls=<class 'int'>, description='Axis along which the boundary is placed', choices=None, required=False, hidden=False, extra={}), Parameter(name='axis_position', default_value=nan, cls=<class 'float'>, description='Position of the boundary along the axis. If omitted, the boundary might not support some operations.', choices=None, required=False, hidden=False, extra={}), Parameter(name='thickness', default_value=1, cls=<class 'float'>, description='Thickness of the boundary, which affects calculations of total amounts and potentially boundary conditions', choices=None, required=False, hidden=False, extra={}), Parameter(name='plot_thickness', default_value=1, cls=<class 'float'>, description='Thickness used when plotting the boundary', choices=None, required=False, hidden=False, extra={}), Parameter(name='label', default_value='', cls=<class 'str'>, description='The name of the field', choices=None, required=False, hidden=False, extra={})]

parameters (with default values) of this subclass

Type:: list

plot(colorbar: bool = False, *args, title: str | None = None, filename: str | None = None, action: Literal['auto', 'close', 'none', 'sca', 'show'] = 'auto', ax_style: dict[str, Any] | None = None, fig_style: dict[str, Any] | None = None, ax=None, **kwargs)[source]

Plot the boundary field element.

Parameters:

title (str) – Title of the plot. If omitted, the title might be chosen automatically.
filename (str, optional) – If given, the plot is written to the specified file.
action (str) – Decides what to do with the final figure. If the argument is set to show, matplotlib.pyplot.show() will be called to show the plot. If the value is auto or none, the figure will be created, but not necessarily shown. The value close closes the figure, after saving it to a file when filename is given.
ax_style (dict) – Dictionary with properties that will be changed on the axis after the plot has been drawn by calling matplotlib.pyplot.setp(). A special item i this dictionary is use_offset, which is flag that can be used to control whether offset are shown along the axes of the plot.
fig_style (dict) – Dictionary with properties that will be changed on the figure after the plot has been drawn by calling matplotlib.pyplot.setp(). For instance, using fig_style={‘dpi’: 200} increases the resolution of the figure.
ax (matplotlib.axes.Axes) – Figure axes to be used for plotting. The special value “create” creates a new figure, while “reuse” attempts to reuse an existing figure, which is the default.
colorbar (bool) – Flag determining whether a colorbar is shown.
**kwargs – All remaining parameters are forwarded to matplotlib.axes.Axes.pcolormesh

Bases: FieldElementBase

Element representing a scalar spatially-resolved field.

Parameters Dictionary:

grid: The grid on which the field is discretized (default=None)
label: The name of the field (default=’’)
plot_args: Extra arguments for plotting this element (default={})

Parameters:

data (ndarray or float, optional) – Field values at the support points of the grid
parameters (dict) – Additional parameters determining how the element behaves. Most importantly, the entry ‘grid’ determines the discretization grid on which this field is defined.

Parameters of ScalarFieldElement:

plot_args: Extra arguments for plotting this element (Default value: {})
grid: The grid on which the field is discretized. The grid also determines the space dimension and its extension. (Default value: None)
label: The name of the field (Default value: '')

add_amount(point: ndarray, amount: float)[source]

Add the given amount to the field.

Parameters:

point (ndarray) – Point where the amount is added to the field
amount (float) – The total amount added to the field

copy(method: Literal['clean', 'shallow', 'data'] = 'data', data=None)[source]

Create a copy of the state.

Parameters:

method (str) – Determines whether a clean, shallow, or data copy is performed. See copy() for details.
data – Data to be used instead of the one in the current state. This data is used as is and not copied!

Returns:

A copy of the current state object

property data: ndarray

Value at the valid grid points.

Type:: ndarray

property degrees_of_freedom: int

the number of degrees of freedom for this element

Type:: int

property field: ScalarField

the scalar field.

Type:: ScalarField

classmethod from_field(field: ScalarField, parameters: dict[str, Any] | None = None) → ScalarFieldElement[source]

Create a scalar field element from a scalar field.

Parameters:

field (ScalarField) – The scalar field that initializes the element
parameters (dict) – Additional parameters determining how the element behaves. Note that the entries ‘grid’ and ‘label’ will be overwriten by the data from field.

Returns:

The initialized instance

Return type:

ScalarFieldElement

get_concentration(points: ndarray)[source]

Determine concentration at the given points.

Parameters:: points (ndarray) – The coordinates of the single point or the list of points at which the concentration is returned

property grid: CartesianGrid

discretization grid.

Type:: CartesianGrid

make_add_amount_compiled() → Callable[source]

Get a compiled function for adding amount to the field.

Returns:: a function with signature (data: ndarray, point: ndarray, amount: float), which adds amount to the field state given by data at point point.
Return type:: callable

make_get_concentration_compiled() → Callable[source]

Get a compiled function for obtaining concentrations.

Returns:: a function with signature (data: ndarray, point: ndarray), which determines the concentration at point point given the field state data.
Return type:: callable

parameters_default = [Parameter(name='grid', default_value=None, cls=<class 'object'>, description='The grid on which the field is discretized. The grid also determines the space dimension and its extension.', choices=None, required=False, hidden=False, extra={'serializer': <function ScalarFieldElement.<lambda>>, 'unserializer': <bound method GridBase.from_state of <class 'pde.grids.base.GridBase'>>}), Parameter(name='label', default_value='', cls=<class 'str'>, description='The name of the field', choices=None, required=False, hidden=False, extra={})]

parameters (with default values) of this subclass

Type:: list

plot(ax=None, **kwargs)[source]

Plot the field.

This simply calls plot() and all arguments are forwarded to this method.

property total_amount: float

the total material amount in the field

Type:: float