Class mgrid::FDArray

2-D scalar field on a finite-difference grid: FDBase geometry plus an owningField2D of element values.More...

#include <fdarray.hpp>

Inherits the following classes: mgrid::FDBase

Public Attributes

Type	Name
BoundaryConditions	boundaryConditions Per-edge boundary conditions; public to match the legacy API.

Public Functions

Type	Name
	FDArray () = default Constructs an empty array with no geometry and no storage.
	FDArray (double aspect, int nx, int nz) Constructs an `nx` by`nz` array, sized, zeroed, with geometry.
	FDArray (const FDArray &) = default Defaulted copy constructor (deep-copies geometry and storage).
	FDArray (FDArray &&) = default Defaulted move constructor.
double	calculate_flux () const Integrates the field over the domain using extended Simpson's rule.
int	cols () noexcept const Number of columns (z-direction grid points).
double *	data () noexcept Pointer to the contiguous row-major element storage.
const double *	data () noexcept const Pointer to the contiguous row-major element storage.
void	derivatives (Deriv & d, int i, int j) const Fills all ten derivative members from the pointwise methods.
double	dx (int i, int j) const First derivative ∂f/∂x at (i, j): centred, one-sided at bounded ends, wrapped on a periodic x-axis.
void	dx (Field2D & out) const Computes first derivatives in the x direction at all grid points.
double	dxu (int i, int j) const First derivative of a uniform field (u = 1 everywhere) in the x direction.
double	dxx (int i, int j) const Second derivative in the x direction at grid point (i, j).
void	dxx (Field2D & out) const Computes second derivatives in the x direction at all grid points.
double	dxxu (int i, int j) const Second derivative of a uniform field (u = 1 everywhere) in the x direction.
double	dxz (int i, int j) const Mixed second derivative ∂²f/∂x∂z at grid point (i, j).
void	dxz (Field2D & out) const Computes mixed second derivatives at all grid points.
double	dxzu (int i, int j) const Mixed second derivative of a uniform field (u = 1 everywhere) ∂²u/∂x∂z.
double	dz (int i, int j) const First derivative ∂f/∂z at (i, j): centred, one-sided at bounded ends, wrapped on a periodic z-axis.
void	dz (Field2D & out) const Computes first derivatives in the z direction at all grid points.
double	dzu (int i, int j) const First derivative of a uniform field (u = 1 everywhere) in the z direction.
double	dzz (int i, int j) const Second derivative in the z direction at grid point (i, j).
void	dzz (Field2D & out) const Computes second derivatives in the z direction at all grid points.
double	dzzu (int i, int j) const Second derivative of a uniform field (u = 1 everywhere) in the z direction.
Field2D &	field () noexcept Mutable access to the underlying value field.
const Field2D &	field () noexcept const Read-only access to the underlying value field.
void	gradient (FDVecArray & result) const Populates a vector array with the gradient at each grid point.
void	gradient_magnitude (Field2D & out) const Computes the magnitude of the gradient at all grid points.
double	norm () const Root-mean-square element magnitude of the field.
double &	operator() (int i, int j) Accesses the element at row `i` , column`j` .
double	operator() (int i, int j) const Reads the element at row `i` , column`j` .
FDArray &	*operator=** (double s) Multiplies every element by the scalar `s` .
FDArray &	*operator= (const FDArray** & o) Element-wise multiplies by the values of `o` .
FDArray &	operator+= (double s) Adds the scalar `s` to every element.
FDArray &	operator+= (const Field2D & v) Element-wise adds `v` .
FDArray &	operator+= (const FDArray & o) Element-wise adds the values of `o` .
FDArray &	operator-= (double s) Subtracts the scalar `s` from every element.
FDArray &	operator-= (const Field2D & v) Element-wise subtracts `v` .
FDArray &	operator-= (const FDArray & o) Element-wise subtracts the values of `o` .
FDArray &	operator/= (double s) Divides every element by the scalar `s` .
FDArray &	operator/= (const FDArray & o) Element-wise divides by the values of `o` .
FDArray &	operator= (FDArray &&) = default Defaulted move assignment.
FDArray &	operator= (double s) Fills every element with the scalar `s` .
FDArray &	operator= (const Field2D & v) Copies element values from `v` , leaving geometry and boundaries.
FDArray &	operator= (const FDArray & o) Copies element values from `o` only; geometry and boundaries are left unchanged.
FDArray &	operator= (const std::function< double(double, double)> & f) Sets `(this)(i, j) = f(i hx, j * hz)` over every grid point.
double &	operator[] (int i, int j) Accesses the element at row `i` , column`j` (C++23 subscript).
double	operator[] (int i, int j) const Reads the element at row `i` , column`j` (C++23 subscript).
void	resize (double aspect, int nx, int nz, AxisKind kx=AxisKind::bounded, AxisKind kz=AxisKind::bounded) Recomputes geometry and reallocates storage and boundaries.
int	rows () noexcept const Number of rows (x-direction grid points).
void	update_boundaries () Applies each edge's boundary conditions to the field.
virtual void	write (std::string filestring) Writes the field to a netCDF-4 file.
	~FDArray () override Defaulted destructor.

Public Functions inherited from mgrid::FDBase

See mgrid::FDBase

Type	Name
	FDBase () = default
	FDBase (const FDBase &) = default
	FDBase (FDBase &&) = default
FDBase &	operator= (const FDBase &) = default
FDBase &	operator= (FDBase &&) = default
double	spacing (int n) const Get the grid spacing in a given direction.
const Axis &	x_axis () const The x grid axis (points, spacing, periodicity).
const Axis &	z_axis () const The z grid axis (points, spacing, periodicity).
virtual	~FDBase () = default

Protected Attributes inherited from mgrid::FDBase

See mgrid::FDBase

Type	Name
double	aspect_ = `{0.0}`
double	hx_ = `{0.0}`
double	hz_ = `{0.0}`
int	nx_ = `{0}`
int	nz_ = `{0}`
Axis	xAxis_ = `{}`
double	xfactor_ = `{0.0}`
double	xxfactor_ = `{0.0}`
double	xzfactor_ = `{0.0}`
Axis	zAxis_ = `{}`
double	zfactor_ = `{0.0}`
double	zzfactor_ = `{0.0}`

Protected Functions inherited from mgrid::FDBase

See mgrid::FDBase

Type	Name
void	calculate_geometry (double aspect, int nx, int nz, AxisKind kx=AxisKind::bounded, AxisKind kz=AxisKind::bounded) Compute and cache grid spacings and finite-difference factors.

Detailed Description

Composition, not inheritance, over the storage: the grid spacings and stencil factors come from FDBase, while the values live in a private Field2D. resize is the only geometry-changing entry point; the assignment operators touch element values only.

Public Attributes Documentation

variable boundaryConditions

Per-edge boundary conditions; public to match the legacy API.

BoundaryConditions mgrid::FDArray::boundaryConditions;

Public Functions Documentation

function FDArray [1/4]

Constructs an empty array with no geometry and no storage.

mgrid::FDArray::FDArray () = default

function FDArray [2/4]

Constructs an nx bynz array, sized, zeroed, with geometry.

mgrid::FDArray::FDArray (
    double aspect,
    int nx,
    int nz
)

Parameters:

aspect aspect ratio (horizontal extent / vertical extent)
nx number of grid points in the x direction (rows)
nz number of grid points in the z direction (columns)

function FDArray [3/4]

Defaulted copy constructor (deep-copies geometry and storage).

mgrid::FDArray::FDArray (
    const FDArray &
) = default

function FDArray [4/4]

Defaulted move constructor.

mgrid::FDArray::FDArray (
    FDArray &&
) = default

function calculate_flux

Integrates the field over the domain using extended Simpson's rule.

double mgrid::FDArray::calculate_flux () const

Returns:

the double integral of the field using Newton-Cotes quadrature

Note:

Not defined for periodic axes: the extended-Simpson end weights assume physical boundaries. Asserts !x_axis().periodic && !z_axis().periodic.

function cols

Number of columns (z-direction grid points).

inline int mgrid::FDArray::cols () noexcept const

Returns:

the column count

function data [1/2]

Pointer to the contiguous row-major element storage.

inline double * mgrid::FDArray::data () noexcept

Returns:

pointer to element (0, 0)

function data [2/2]

Pointer to the contiguous row-major element storage.

inline const double * mgrid::FDArray::data () noexcept const

Returns:

const pointer to element (0, 0)

function derivatives

Fills all ten derivative members from the pointwise methods.

inline void mgrid::FDArray::derivatives (
    Deriv & d,
    int i,
    int j
) const

Parameters:

d output struct to receive all derivative values
i row index
j column index

function dx [1/2]

First derivative ∂f/∂x at (i, j): centred, one-sided at bounded ends, wrapped on a periodic x-axis.

inline double mgrid::FDArray::dx (
    int i,
    int j
) const

Parameters:

i row index
j column index

Returns:

∂f/∂x (second-order): forward difference at a bounded low end, backward at a bounded high end, centred (with wrapped neighbour indices on a periodic axis) elsewhere.

function dx [2/2]

Computes first derivatives in the x direction at all grid points.

inline void mgrid::FDArray::dx (
    Field2D & out
) const

Parameters:

out output field to receive dx values

function dxu

First derivative of a uniform field (u = 1 everywhere) in the x direction.

inline double mgrid::FDArray::dxu (
    int i,
    int j
) const

Parameters:

i row index
j column index

Returns:

∂u/∂x for u=1 (i.e. the stencil's own-point coefficient); 0 at every point of a periodic x-axis.

function dxx [1/2]

Second derivative in the x direction at grid point (i, j).

inline double mgrid::FDArray::dxx (
    int i,
    int j
) const

Parameters:

i row index
j column index

Returns:

∂²f/∂x² using forward finite differences at boundaries, centered interior

Note:

Uses forward difference at i=0, backward at i=nx_-1, centered elsewhere.

function dxx [2/2]

Computes second derivatives in the x direction at all grid points.

inline void mgrid::FDArray::dxx (
    Field2D & out
) const

Parameters:

out output field to receive dxx values

function dxxu

Second derivative of a uniform field (u = 1 everywhere) in the x direction.

inline double mgrid::FDArray::dxxu (
    int i,
    int j
) const

Parameters:

i row index
j column index

Returns:

∂²u/∂x² for u=1

function dxz [1/2]

Mixed second derivative ∂²f/∂x∂z at grid point (i, j).

inline double mgrid::FDArray::dxz (
    int i,
    int j
) const

Parameters:

i row index
j column index

Returns:

the mixed partial derivative using a 9-region stencil (4 corners, 4 edges, interior)

Note:

Uses forward/backward/centered differences at bounded boundaries; the standard mixed partial (no folded sign). One corner branch (i==nx_-1, j==0) corrects a sign typo in the 2011 source; the one-sided coefficient sets are transcribed verbatim. Every centred neighbour index is taken through Axis::shift, so it wraps on a periodic axis and is the identity (i + d) on a bounded one: a doubly-periodic dxz is the interior 9-point form with both indices wrapped, and a mixed array wraps only the periodic axis while the bounded axis still selects its one-sided edge branch.

function dxz [2/2]

Computes mixed second derivatives at all grid points.

inline void mgrid::FDArray::dxz (
    Field2D & out
) const

Parameters:

out output field to receive dxz values

function dxzu

Mixed second derivative of a uniform field (u = 1 everywhere) ∂²u/∂x∂z.

inline double mgrid::FDArray::dxzu (
    int i,
    int j
) const

Parameters:

i row index
j column index

Returns:

∂²u/∂x∂z for u=1, exact for uniform fields

Note:

Uses a 9-region stencil; the result is mostly zero with non-zero values at corners.

function dz [1/2]

First derivative ∂f/∂z at (i, j): centred, one-sided at bounded ends, wrapped on a periodic z-axis.

inline double mgrid::FDArray::dz (
    int i,
    int j
) const

Parameters:

i row index
j column index

Returns:

∂f/∂z (second-order): forward difference at a bounded low end, backward at a bounded high end, centred (with wrapped neighbour indices on a periodic axis) elsewhere.

function dz [2/2]

Computes first derivatives in the z direction at all grid points.

inline void mgrid::FDArray::dz (
    Field2D & out
) const

Parameters:

out output field to receive dz values

function dzu

First derivative of a uniform field (u = 1 everywhere) in the z direction.

inline double mgrid::FDArray::dzu (
    int i,
    int j
) const

Parameters:

i row index
j column index

Returns:

∂u/∂z for u=1 (i.e. the stencil's own-point coefficient); 0 at every point of a periodic z-axis.

function dzz [1/2]

Second derivative in the z direction at grid point (i, j).

inline double mgrid::FDArray::dzz (
    int i,
    int j
) const

Parameters:

i row index
j column index

Returns:

∂²f/∂z² using forward finite differences at boundaries, centered interior

Note:

Uses forward difference at j=0, backward at j=nz_-1, centered elsewhere.

function dzz [2/2]

Computes second derivatives in the z direction at all grid points.

inline void mgrid::FDArray::dzz (
    Field2D & out
) const

Parameters:

out output field to receive dzz values

function dzzu

Second derivative of a uniform field (u = 1 everywhere) in the z direction.

inline double mgrid::FDArray::dzzu (
    int i,
    int j
) const

Parameters:

i row index
j column index

Returns:

∂²u/∂z² for u=1

function field [1/2]

Mutable access to the underlying value field.

inline Field2D & mgrid::FDArray::field () noexcept

Returns:

reference to the owned Field2D

function field [2/2]

Read-only access to the underlying value field.

inline const Field2D & mgrid::FDArray::field () noexcept const

Returns:

const reference to the owned Field2D

function gradient

Populates a vector array with the gradient at each grid point.

void mgrid::FDArray::gradient (
    FDVecArray & result
) const

Parameters:

result output vector array; filled with (dx, dz) pairs at each grid point

Postcondition:

result.first(i,j) = dx(i,j) and result.second(i,j) = dz(i,j) for all (i,j) i.e. result is the true gradient (∂f/∂x, ∂f/∂z).

function gradient_magnitude

Computes the magnitude of the gradient at all grid points.

inline void mgrid::FDArray::gradient_magnitude (
    Field2D & out
) const

Parameters:

out output field to receive sqrt(dx^2 + dz^2) at each point

function norm

Root-mean-square element magnitude of the field.

inline double mgrid::FDArray::norm () const

Returns:

frobenius_norm(field()) — RMS, not the true Frobenius norm, matching the legacy FDArray::norm.

function operator()

Accesses the element at row i , columnj .

inline double & mgrid::FDArray::operator() (
    int i,
    int j
)

Parameters:

i row index
j column index

Returns:

reference to the element

Note:

No bounds checking is performed.

function operator()

Reads the element at row i , columnj .

inline double mgrid::FDArray::operator() (
    int i,
    int j
) const

Parameters:

i row index
j column index

Returns:

a copy of the element

Note:

No bounds checking is performed.

function operator*=

Multiplies every element by the scalar s .

inline FDArray & mgrid::FDArray::operator*= (
    double s
)

Parameters:

s scalar factor

Returns:

*this

function operator*=

Element-wise multiplies by the values of o .

inline FDArray & mgrid::FDArray::operator*= (
    const FDArray & o
)

Parameters:

o operand array of matching shape

Returns:

*this

Exception:

std::invalid_argument if the shapes differ

function operator+=

Adds the scalar s to every element.

inline FDArray & mgrid::FDArray::operator+= (
    double s
)

Parameters:

s scalar addend

Returns:

*this

function operator+=

Element-wise adds v .

inline FDArray & mgrid::FDArray::operator+= (
    const Field2D & v
)

Parameters:

v operand field of matching shape

Returns:

*this

Exception:

std::invalid_argument if the shapes differ

function operator+=

Element-wise adds the values of o .

inline FDArray & mgrid::FDArray::operator+= (
    const FDArray & o
)

Parameters:

o operand array of matching shape

Returns:

*this

Exception:

std::invalid_argument if the shapes differ

function operator-=

Subtracts the scalar s from every element.

inline FDArray & mgrid::FDArray::operator-= (
    double s
)

Parameters:

s scalar subtrahend

Returns:

*this

function operator-=

Element-wise subtracts v .

inline FDArray & mgrid::FDArray::operator-= (
    const Field2D & v
)

Parameters:

v operand field of matching shape

Returns:

*this

Exception:

std::invalid_argument if the shapes differ

function operator-=

Element-wise subtracts the values of o .

inline FDArray & mgrid::FDArray::operator-= (
    const FDArray & o
)

Parameters:

o operand array of matching shape

Returns:

*this

Exception:

std::invalid_argument if the shapes differ

function operator/=

Divides every element by the scalar s .

inline FDArray & mgrid::FDArray::operator/= (
    double s
)

Parameters:

s scalar divisor

Returns:

*this

function operator/=

Element-wise divides by the values of o .

inline FDArray & mgrid::FDArray::operator/= (
    const FDArray & o
)

Parameters:

o operand array of matching shape

Returns:

*this

Exception:

std::invalid_argument if the shapes differ

function operator=

Defaulted move assignment.

FDArray & mgrid::FDArray::operator= (
    FDArray &&
) = default

function operator=

Fills every element with the scalar s .

inline FDArray & mgrid::FDArray::operator= (
    double s
)

Parameters:

s value written into every element

Returns:

*this

function operator=

Copies element values from v , leaving geometry and boundaries.

inline FDArray & mgrid::FDArray::operator= (
    const Field2D & v
)

Parameters:

v source field; must have the same shape as *this

Returns:

*this

Exception:

std::invalid_argument if the shapes differ

function operator=

Copies element values from o only; geometry and boundaries are left unchanged.

FDArray & mgrid::FDArray::operator= (
    const FDArray & o
)

Parameters:

o source array; must have the same shape as *this

Returns:

*this

Exception:

std::invalid_argument if the shapes differ

function operator=

Sets (*this)(i, j) = f(i * hx, j * hz) over every grid point.

FDArray & mgrid::FDArray::operator= (
    const std::function< double(double, double)> & f
)

Parameters:

f callable sampled at each point's physical coordinates

Returns:

*this

function operator[]

Accesses the element at row i , columnj (C++23 subscript).

inline double & mgrid::FDArray::operator[] (
    int i,
    int j
)

Parameters:

i row index
j column index

Returns:

reference to the element

Note:

No bounds checking is performed.

function operator[]

Reads the element at row i , columnj (C++23 subscript).

inline double mgrid::FDArray::operator[] (
    int i,
    int j
) const

Parameters:

i row index
j column index

Returns:

a copy of the element

Note:

No bounds checking is performed.

function resize

Recomputes geometry and reallocates storage and boundaries.

void mgrid::FDArray::resize (
    double aspect,
    int nx,
    int nz,
    AxisKind kx=AxisKind::bounded,
    AxisKind kz=AxisKind::bounded
)

Parameters:

aspect aspect ratio (horizontal extent / vertical extent)
nx new number of grid points in the x direction (rows)
nz new number of grid points in the z direction (columns)
kx kind of the x axis; periodic threads through to calculate_geometry and sets the left/right edges to periodicCondition. Defaults to bounded.
kz kind of the z axis; periodic threads through to calculate_geometry and sets the top/bottom edges to periodicCondition. Defaults to bounded.

Postcondition:

Every element is zero; each bounded edge is zeroed, each periodic edge holds periodicCondition.

function rows

Number of rows (x-direction grid points).

inline int mgrid::FDArray::rows () noexcept const

Returns:

the row count

function update_boundaries

Applies each edge's boundary conditions to the field.

void mgrid::FDArray::update_boundaries ()

Note:

Sweeps the four edges in turn. At each boundary node a Dirichlet point sets the node value directly, while a Neumann point uses a 4th-order one-sided stencil stepping inward from the edge.

Note:

Domain corner nodes are owned by the left/right (vertical) edges: the horizontal (top/bottom) sweeps skip their end indices, matching the corner convention of spec §5.5.

function write

Writes the field to a netCDF-4 file.

virtual void mgrid::FDArray::write (
    std::string filestring
)

Parameters:

filestring output path stem; .nc is appended before writing.

Postcondition:

The file holds dims x = rows(), z = cols() and one 2-D double variable "value" in row-major order.

Exception:

netCDF::exceptions::NcException on any netCDF failure.

function ~FDArray

Defaulted destructor.

mgrid::FDArray::~FDArray () override

The documentation for this class was generated from the following file include/multigrid/fdarray.hpp