bice.pde package

Submodules

bice.pde.finite_differences module

Finite difference discretization schemes and boundary conditions.

class AffineOperator(Q: ndarray | spmatrix, G: float | ndarray[tuple[Any, ...], dtype[float64 | complexfloating]] = 0)

Bases: object

Wrapper object for an affine operator of the form Op: u –> Q*u + G.

Used for including boundary conditions into differentiation operators.

Initialize the AffineOperator.

Parameters:

Q – The linear part (matrix).
G – The constant (affine) part.

G: float | ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]: constant (affine) part

Q: ndarray | spmatrix: linear part

Apply the operator to a vector/tensor u.

Parameters:

u – The vector/tensor to apply the operator to. If None, returns the linear matrix part Q.
g – Scaling factor for the constant part G.

Returns:

The result of Q*u + g*G, or the matrix Q if u is None.

Return type:

Union[Matrix, Array]

dot(u: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]) → ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]

Apply the operator to a vector u.

Equivalent to self.__call__(u).

Parameters:: u – The vector to apply the operator to.
Returns:: The result of the operator application.
Return type:: Array

is_linear() → bool

Check if the operator is linear (i.e., G=0).

Returns:: True if linear, False otherwise.
Return type:: bool

DirichletBC(vals: tuple[float, float] = (0.0, 0.0)) → RobinBC

Create Dirichlet boundary conditions: u(left) = vals[0], u(right) = vals[1].

Parameters:: vals – Tuple of (left, right) values.
Returns:: The configured boundary conditions.
Return type:: RobinBC

class FDBoundaryConditions

Bases: object

Base class for finite difference boundary conditions.

Applied using an affine transformation u_pad = Q*u + G.

Initialize the boundary conditions.

G: float | ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]: constant part of the boundary operator

Q: ndarray | spmatrix | None: linear part of the boundary operator

pad(u: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]) → ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]

Transform a vector u to the boundary padded vector u_pad = Q*u + G.

Parameters:: u – The vector of unknowns.
Returns:: The padded vector.
Return type:: Array

pad_x(x: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]) → ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]

Pad the vector of node values with the x-values of the ghost nodes.

Parameters:: x – The spatial grid points.
Returns:: The padded grid points.
Return type:: Array

update(x: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]], approx_order: int) → None

Build the matrix and constant part for the boundary transformation.

Parameters:

x – The spatial grid points.
approx_order – The approximation order of the FD scheme.

class FiniteDifferencesEquation(shape: int | tuple[int, ...] | None = None)

Bases: PartialDifferentialEquation

Spatially discretized equation using a finite difference scheme.

Provides routines for building differentiation matrices and managing boundary conditions. Uses the ‘findiff’ package for matrix generation.

Initialize the FiniteDifferencesEquation.

Parameters:: shape – The shape of the unknowns.

adapt() → tuple[float, float] | None

Perform adaption of the grid to the solution.

Currently only supported for 1D spatial domains. Interpolates unknowns and history to the new grid points.

bc: FDBoundaryConditions | None: the boundary conditions, if None, defaults to periodic BCs

build_FD_matrices(approx_order: int = 2) → list[list[AffineOperator | ndarray | spmatrix]]

Build finite difference differentiation matrices.

Supports 1D and 2D domains. 2D matrices are constructed from 1D operators using Kronecker products.

Parameters:: approx_order – The desired approximation order of the finite difference scheme.
Returns:: The list of built differentiation matrices.
Return type:: list
Raises:: NotImplementedError – If spatial dimension is higher than 2.

build_FD_matrices_1d(approx_order: int = 2, x: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]] | None = None) → list[AffineOperator]

Build 1D finite difference differentiation matrices.

Uses the Fornberg (1988) algorithm for generating weights.

Parameters:

approx_order – The desired approximation order of the finite difference scheme.
x – The spatial grid points. If None, uses self.x[0].

Returns:

The list of 1D differentiation operators.

Return type:

list of AffineOperator

ddx: list[list[AffineOperator | ndarray | spmatrix]]

du_dx(u: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]] | None = None, direction: int = 0) → ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]

Calculate the spatial derivative in a given direction.

Parameters:

u – The vector of unknowns.
direction – The spatial direction index.

Returns:

The spatial derivative vector.

Return type:

Array

jacobian(u: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]) → ndarray | spmatrix

Calculate the Jacobian of the equation.

Parameters:: u – The vector of unknowns.
Returns:: The Jacobian matrix, typically as a CSR sparse matrix.
Return type:: Matrix

laplace: AffineOperator | ndarray | spmatrix | None: second order derivative operator (Laplacian)

load(data: dict[str, Any]) → None

Load the state of the equation, including the x-values.

Parameters:: data – The state dictionary to load from.

max_dx: maximum grid size for mesh adaption

max_refinement_error

maximum error tolerance

Type:: mesh adaption

min_dx: minimum grid size for mesh adaption

min_refinement_error

minimum error tolerance

Type:: mesh adaption

nabla: AffineOperator | list[ndarray | spmatrix] | None: first order derivative operator

refinement_error_estimate() → ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]

Estimate the error made in each grid point.

Calculates the integral of curvature as an error estimate.

Returns:: The error estimate at each grid point.
Return type:: Array

save() → dict[str, Any]

Save the state of the equation, including the x-values.

Returns:: The state dictionary.
Return type:: dict

x: list[ndarray[tuple[Any, ...], dtype[float64]]] | None: the spatial coordinates

NeumannBC(vals: tuple[float, float] = (0.0, 0.0)) → RobinBC

Create Neumann boundary conditions: u’(left) = vals[0], u’(right) = vals[1].

Parameters:: vals – Tuple of (left, right) derivative values.
Returns:: The configured boundary conditions.
Return type:: RobinBC

class NoBoundaryConditions

Bases: FDBoundaryConditions

Boundary conditions with no ghost points.

Useful for building differentiation matrices that do not imply any specific boundary conditions.

Initialize the boundary conditions.

pad_x(x: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]) → ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]

No padding for grid points.

Parameters:: x – The grid points.
Returns:: The original grid points.
Return type:: Array

update(x: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]], approx_order: int) → None

Build an identity transformation.

Parameters:

x – The grid points.
approx_order – The approximation order.

class PeriodicBC

Bases: FDBoundaryConditions

Periodic boundary conditions for finite difference schemes.

Initialize the periodic boundary conditions.

boundary_dx: float | None: the virtual distance between the left and right boundary node

order: how many ghost nodes at each boundary?

pad_x(x: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]) → ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]

Pad grid points with periodic ghost points.

Parameters:: x – The grid points.
Returns:: The padded grid points.
Return type:: Array

update(x: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]], approx_order: int) → None

Build the transformation for periodic boundaries.

Parameters:

x – The spatial grid points.
approx_order – The approximation order.

class RobinBC(a: tuple[float, float] = (0.0, 0.0), b: tuple[float, float] = (1.0, 1.0), c: tuple[float, float] = (0.0, 0.0))

Bases: FDBoundaryConditions

Robin boundary conditions of the form a*u(x_b) + b*u’(x_b) = c.

Initialize Robin boundary conditions.

Parameters:

a – Tuple (left, right) of coefficients for u.
b – Tuple (left, right) of coefficients for u’.
c – Tuple (left, right) of values for the boundary condition.

update(x: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]], approx_order: int) → None

Build the transformation for Robin boundaries.

Parameters:

x – The grid points.
approx_order – The approximation order.

bice.pde.pde module

Base classes for partial differential equations (PDEs).

class PartialDifferentialEquation(shape: int | tuple[int, ...] | None = None)

Bases: Equation

Abstract base class for spatially discretized equations.

Serves as a parent class for more specific implementations such as pseudospectral or finite difference schemes.

Initialize the PDE.

Parameters:: shape – The shape of the unknowns.

du_dt(u: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]] | None = None) → ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]

Calculate the time derivative du/dt of the unknowns.

Parameters:: u – The vector of unknowns. If None, the current state self.u is used.
Returns:: The time derivative vector.
Return type:: Array

du_dx(u: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]] | None = None, direction: int = 0) → ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]

Calculate the spatial derivative du/dx in a given direction.

Parameters:

u – The vector of unknowns.
direction – The index of the spatial direction (e.g., 0 for x, 1 for y).

Returns:

The spatial derivative vector.

Return type:

Array

Raises:

NotImplementedError – This is an abstract method.

property spatial_dimension: int

Return the spatial dimension of the domain.

Returns:: The spatial dimension.
Return type:: int

x: list[ndarray[tuple[Any, ...], dtype[float64]]] | ndarray[tuple[Any, ...], dtype[float64]] | None: the spatial coordinates

bice.pde.pseudospectral module

Pseudospectral discretization for Partial Differential Equations.

class PseudospectralEquation(shape: int | tuple[int, ...] | None = None)

Bases: PartialDifferentialEquation

Base class for PDEs using a pseudospectral scheme.

The PseudospectralEquation is a subclass of the PartialDifferentialEquation and provides some useful routines that are needed for implementing PDEs with a pseudospectral scheme.

Initialize the PDE.

Parameters:: shape – The shape of the unknowns.

build_kvectors(real_fft: bool = False) → None

Build the k-vectors for the Fourier space.

Set real=True, if real input to the FFT can be assumed (rfft) (the k-vectors will be smaller and rfft is more performant than fft).

k: list[ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]] | None: the wavevector

Module contents

Partial Differential Equation (PDE) discretization schemes.

This package provides base classes for different spatial discretization methods, such as finite differences and pseudospectral methods.

class FiniteDifferencesEquation(shape: int | tuple[int, ...] | None = None)

Bases: PartialDifferentialEquation

Spatially discretized equation using a finite difference scheme.

Provides routines for building differentiation matrices and managing boundary conditions. Uses the ‘findiff’ package for matrix generation.

Initialize the FiniteDifferencesEquation.

Parameters:: shape – The shape of the unknowns.

adapt() → tuple[float, float] | None

Perform adaption of the grid to the solution.

Currently only supported for 1D spatial domains. Interpolates unknowns and history to the new grid points.

bc: FDBoundaryConditions | None: the boundary conditions, if None, defaults to periodic BCs

build_FD_matrices(approx_order: int = 2) → list[list[AffineOperator | ndarray | spmatrix]]

Build finite difference differentiation matrices.

Supports 1D and 2D domains. 2D matrices are constructed from 1D operators using Kronecker products.

Parameters:: approx_order – The desired approximation order of the finite difference scheme.
Returns:: The list of built differentiation matrices.
Return type:: list
Raises:: NotImplementedError – If spatial dimension is higher than 2.

build_FD_matrices_1d(approx_order: int = 2, x: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]] | None = None) → list[AffineOperator]

Build 1D finite difference differentiation matrices.

Uses the Fornberg (1988) algorithm for generating weights.

Parameters:

approx_order – The desired approximation order of the finite difference scheme.
x – The spatial grid points. If None, uses self.x[0].

Returns:

The list of 1D differentiation operators.

Return type:

list of AffineOperator

ddx: list[list[AffineOperator | ndarray | spmatrix]]

du_dx(u: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]] | None = None, direction: int = 0) → ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]

Calculate the spatial derivative in a given direction.

Parameters:

u – The vector of unknowns.
direction – The spatial direction index.

Returns:

The spatial derivative vector.

Return type:

Array

jacobian(u: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]) → ndarray | spmatrix

Calculate the Jacobian of the equation.

Parameters:: u – The vector of unknowns.
Returns:: The Jacobian matrix, typically as a CSR sparse matrix.
Return type:: Matrix

laplace: AffineOperator | ndarray | spmatrix | None: second order derivative operator (Laplacian)

load(data: dict[str, Any]) → None

Load the state of the equation, including the x-values.

Parameters:: data – The state dictionary to load from.

max_dx: maximum grid size for mesh adaption

max_refinement_error

maximum error tolerance

Type:: mesh adaption

min_dx: minimum grid size for mesh adaption

min_refinement_error

minimum error tolerance

Type:: mesh adaption

nabla: AffineOperator | list[ndarray | spmatrix] | None: first order derivative operator

refinement_error_estimate() → ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]

Estimate the error made in each grid point.

Calculates the integral of curvature as an error estimate.

Returns:: The error estimate at each grid point.
Return type:: Array

save() → dict[str, Any]

Save the state of the equation, including the x-values.

Returns:: The state dictionary.
Return type:: dict

x: list[ndarray[tuple[Any, ...], dtype[float64]]] | None: the spatial coordinates

class PartialDifferentialEquation(shape: int | tuple[int, ...] | None = None)

Bases: Equation

Abstract base class for spatially discretized equations.

Serves as a parent class for more specific implementations such as pseudospectral or finite difference schemes.

Initialize the PDE.

Parameters:: shape – The shape of the unknowns.

du_dt(u: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]] | None = None) → ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]

Calculate the time derivative du/dt of the unknowns.

Parameters:: u – The vector of unknowns. If None, the current state self.u is used.
Returns:: The time derivative vector.
Return type:: Array

du_dx(u: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]] | None = None, direction: int = 0) → ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]

Calculate the spatial derivative du/dx in a given direction.

Parameters:

u – The vector of unknowns.
direction – The index of the spatial direction (e.g., 0 for x, 1 for y).

Returns:

The spatial derivative vector.

Return type:

Array

Raises:

NotImplementedError – This is an abstract method.

property spatial_dimension: int

Return the spatial dimension of the domain.

Returns:: The spatial dimension.
Return type:: int

x: list[ndarray[tuple[Any, ...], dtype[float64]]] | ndarray[tuple[Any, ...], dtype[float64]] | None: the spatial coordinates

class PseudospectralEquation(shape: int | tuple[int, ...] | None = None)

Bases: PartialDifferentialEquation

Base class for PDEs using a pseudospectral scheme.

The PseudospectralEquation is a subclass of the PartialDifferentialEquation and provides some useful routines that are needed for implementing PDEs with a pseudospectral scheme.

Initialize the PDE.

Parameters:: shape – The shape of the unknowns.

build_kvectors(real_fft: bool = False) → None

Build the k-vectors for the Fourier space.

Set real=True, if real input to the FFT can be assumed (rfft) (the k-vectors will be smaller and rfft is more performant than fft).

k: list[ndarray[tuple[Any, ...], dtype[float64 | complexfloating]]] | None: the wavevector

ksquare: ndarray[tuple[Any, ...], dtype[float64 | complexfloating]] | None

x: list[ndarray[tuple[Any, ...], dtype[float64]]] | ndarray[tuple[Any, ...], dtype[float64]] | None: the spatial coordinates