Field operators

Use this page when a discrete gradient, divergence, flux, or related operator is applied to field values and you need to audit its orientation, spacing, units, boundary treatment, and conservation meaning.

The scientific question¶

How should a continuum differential relation be represented on finite entities, and which identities survive the discretization? An operator is not defined by a stencil alone. Its input and output locations, orientation, spacing or metric, boundary conditions, component basis, and units determine its scientific meaning.

For example, a discrete gradient may map node scalars to oriented edge differences, while a finite-volume divergence may map oriented face fluxes to cell-centered rates. Calling both arrays “derivatives” hides their distinct domains and conservation contracts.

Mathematical objects¶

Let scalar samples $\phi_i$ live at ordered one-dimensional nodes $x_i$ . A forward difference gradient lives on the interval between nodes $i$ and $i+1$ . Its orientation points from $i$ to $i+1$ , and its units are $[\phi]/[x]$ .

For a finite-volume cell $c$ with volume $V_c$ , let face $f$ have outward signed orientation $s_{cf}\in\{-1,+1\}$ relative to the cell, area $A_f$ , and normal flux $q_f$ . A discrete divergence lives at the cell and has units $[q] [A]/[V]$ . Boundary faces require a supplied flux or a rule derived from the boundary conditions. Interior faces must appear with opposite signs in adjacent cells.

Matrices can represent these maps, but the matrix alone does not say whether an inner product includes mass, area, or volume weights. Therefore an algebraic transpose is not automatically the physically meaningful adjoint.

Core derivation¶

A one-dimensional edge gradient and a finite-volume cell divergence can be written as

(G\phi)_{i+1/2}=\frac{\phi_{i+1}-\phi_i}{x_{i+1}-x_i}, \qquad (Dq)_c=\frac{1}{V_c}\sum_{f\in\partial c}s_{cf}A_f q_f.

(1)

In (1), reversing an edge orientation reverses both the numerator ordering and the represented component. For divergence, summing $V_c(Dq)_c$ over cells cancels interior face contributions because the same face has opposite orientation in adjacent cells. What remains is boundary flux:

\sum_c V_c(Dq)_c=\sum_{f\in\partial\Omega}s_f A_f q_f.

(2)

Equation (2) is the discrete conservation statement to test. It depends on consistent incidence, geometry, and boundary accounting; it does not follow merely because a stencil resembles a continuum derivative.

An algebraic adjoint $G^{\mathsf{T}}$ is defined by an unweighted Euclidean inner product. For symmetric positive-definite mass matrices $\mathbf{M}_0$ and $\mathbf{M}_1$ , which are therefore invertible, the weighted algebraic adjoint and its exact inner-product identity are

G^{*}=\mathbf{M}_{0}^{-1}G^{\mathsf{T}}\mathbf{M}_{1}, \qquad \langle G\phi,q\rangle_{\mathbf{M}_{1}} =\langle\phi,G^{*}q\rangle_{\mathbf{M}_{0}}.

(3)

Equation (3) is an algebraic definition and contains no boundary term. A discrete integration-by-parts or summation-by-parts claim instead relates the gradient to a separately defined discrete divergence $D$ . Under one declared matrix convention, that distinct identity is

\langle G\phi,q\rangle_{\mathbf{M}_{1}} =-\langle\phi,Dq\rangle_{\mathbf{M}_{0}} +\phi^{\mathsf{T}}\mathbf{E}_{\partial}q, \qquad G^{\mathsf{T}}\mathbf{M}_{1}+\mathbf{M}_{0}D =\mathbf{E}_{\partial}.

(4)

Here $\mathbf{E}_{\partial}$ represents the boundary bilinear form, including the trace and oriented normal-flux pairing appropriate to the discretization. It is generally nonzero. When the boundary form vanishes, as under suitable periodic or homogeneous boundary conditions, (4) reduces to $D=-G^{*}$ . That relation does not hold for a general nonzero boundary form.

Failure modes and interpretation limits¶

Uniform-spacing stencils applied to nonuniform coordinates may retain the expected units while returning the wrong local scale, value, and convergence behavior, even when shapes match.
Inconsistent face orientation destroys interior-flux cancellation.
Ghost cells or padding without a named boundary condition hide external data.
Applying a node operator to cell-centered values introduces an unstated interpolation.
Coordinate-basis derivatives can omit metric or connection terms on curvilinear domains.
An algebraic adjoint can differ from the continuum adjoint because discrete inner products and boundary terms differ.
Conservation of a discrete sum does not prove accuracy, convergence, stability, or conservation of every physical invariant.
Differentiating field values through a fixed operator does not differentiate a limiter switch, topology choice, or adaptive remeshing decision.

What Jaxstro may add¶

Current jaxstro.spatial, grid utilities, mesh utilities, geometry, and operator utilities remain narrower owners. Existing numerical operator utilities own generic algebraic mechanics; they do not claim field location, metric, boundary, or conservation semantics. jaxstro.fields does not exist, and no common operator package is imminent.

If two real consumers establish a shared contract, Jaxstro may later represent input and output entity locations, signed incidence, metric weights, boundary policies, unit transforms, and operator evidence. The abstraction would wrap scientific semantics around reusable linear maps without taking ownership of domain equations, Riemann solvers, time integrators, or application-specific closures.

Evidence required before implementation¶

Analytic tests must recover constant and linear-field derivatives on uniform and nonuniform domains with the expected convergence order. Unit tests must verify that gradient and divergence outputs carry the derived units. Orientation reversal and entity reordering must preserve the represented result. Boundary tests must cover periodic, prescribed-value, prescribed-flux, and unsupported policies explicitly.

Conservation evidence must verify (2) on structured and unstructured examples, including boundary flux. Adjoint claims require inner-product tests with the actual mass or metric matrices. Summation-by-parts claims require the complete discrete identity, including boundary terms. JAX tests must distinguish derivatives with respect to dynamic field values and coordinates from nondifferentiable topology, limiter, and boundary-policy choices.

Claim boundary¶

These examples define audit questions, not a universal operator API. A passing conservation identity does not establish accuracy or stability, and an algebraic transpose does not establish a continuum adjoint. This documentation promises no module or schedule. Shared ownership remains deferred until two consumers support the same field-location, topology, metric, boundary, unit, and evidence contract.

Connected representations, foundations, and methods¶

Read Fields and domains and Topology and discretization for the objects on which these operators act.
Return to Scientific representations for current ownership boundaries.
Review Functions, units, and scales for dimensional checks and Linear algebra as the language of change for adjoints and inner products.
Compare Linear operators, Grids and conservative bin transfer, and Structured 1D meshes for current narrower methods.