Physical fields and post-processing

Source-generated documentation for field containers, evaluation and physical error quantities. Preserve the executed coefficient basis and select one-sided macrocell values when evaluating a broken field at an interface.

API overview

Source modules

Executed complex acoustic fields and independent physical error integration.

These records select no acoustic method: coefficients and original assembled systems are supplied explicitly by a user-defined variational application.

HelmholtzSolution dataclass

Broken complex pressure and physical normal flux outside absorbing faces.

pressure and trace expose complex coefficients. hybrid retains the exact interleaved real coordinates used by the shared solvers. On absorbing faces the stored multiplier is zero; physical outgoing flux is -iomegau/sqrt(kappa*rho)-g and is included in macro conservation.

sample(cell: int, reference: Any) -> tuple[FloatArray, Any, Any]

Evaluate every fine cell at reference points without averaging interfaces.

Triangles use barycentric coordinates (q,3), rectangles use coordinates (q,2) in [0,1]^2. Return physical points, pressure and gradient with a leading fine-cell axis, preserving every incident value independently.

l2_error(exact: Any, order: int = 8) -> float

Integrate the complex pressure error using the Hermitian absolute square.

gradient_l2_error(exact: Any, order: int = 8) -> float

Integrate the physical complex gradient error, without a frequency weight.

conservation_residuals() -> Any

Return complex macro balances ∮q.n−omega²∫u/kappa−∫f−sum Q_j.

Absorbing flux uses the discrete pressure trace and prescribed g. The result is evaluated through the assembled constant-test equations, including their physical material and face quadrature. With PML, q=-rho^-1Dgrad(u) and the mass integral contains d*u/kappa.

local_helmholtz_error_squared(fine: TriangleMesh | CartesianMacroMesh, coefficients: Any, degree: int, exact: Any, order: int = 8, *, derivative: bool = False) -> float

Integrate one local complex pressure or physical-gradient squared error.

Coefficients use the continuous local Pk/Qk nodal ordering from :func:pymhm.fem.scalar.helmholtz.acoustic_space. exact(points) returns pressure values or, with derivative=True, two physical gradient components. The Hermitian absolute square is integrated using the declared physical Gauss order. No frequency weight or interface averaging is applied; summing these integrals gives the squared broken norm across macro cells.

Physical electromagnetic field records in explicitly supplied DG bases.

Electric/magnetic times remain distinct. These records perform field evaluation and error integration and impose no evolution algorithm or boundary condition.

MaxwellSolution dataclass

Staggered physical fields: E at electric_time and H at magnetic_time.

Cell-local cardinal coefficients interleave physical components. The trace is lambda=H cross n on canonical macrofaces. The broken DG curl is distinct from an H(curl)-conforming reconstruction.

sample(cell: int, barycentric: Any) -> tuple[FloatArray, FloatArray, FloatArray]

Evaluate incident DG polynomials on every local fine cell.

Simplexes use barycentric coordinates; rectangles use (x,y) in [0,1]^2. Every incident value is retained independently at broken interfaces.

l2_errors(electric: Any, magnetic: Any, order: int = 6) -> tuple[float, float]

Integrate physical L² errors at the explicitly distinct staggered times.

Physical mapped-RT field records in the literal executed reference coordinates.

MappedRTDarcySolution dataclass

Mapped H(div) flux, discontinuous scalar-pullback pressure and condensed macro traces.

evaluate(cell: int, points: FloatArray) -> tuple[FloatArray, FloatArray, FloatArray]

Evaluate pressure, physical flux and exact Piola divergence in every local hexahedron.

errors(pressure: Any, flux: Any, order: QuadratureOrder = 6) -> dict[str, float]

Integrate physical pressure/vector-flux L2 errors with independent quadrature.

equilibrium_residuals() -> tuple[FloatArray, ...]

Return every pressure-tested physical divergence/source defect, including cell mass.

Physical displacement and raw Cauchy stress in the executed nodal coordinates.

Elasticity3DSolution dataclass

Broken tetrahedral displacement and raw symmetric three-dimensional Cauchy stress.

The scalar triangular skeleton defines the geometry and P1 face modes; hybrid.trace interleaves three negative-traction components per scalar skeleton coefficient. Raw stress is not automatically H(div)-conforming.

evaluate(cell: int, bary: FloatArray) -> tuple[FloatArray, FloatArray, FloatArray]

Return displacement, full gradient and symmetric stress at barycentric points.

errors(displacement: Any, stress: Any, order: int = 7) -> dict[str, float]

Integrate displacement L2 and raw-stress Frobenius errors over the physical volume.

equilibrium_residuals() -> FloatArray

Return three force and three moment defects from body force and skeletal traction.

Physical scalar and conservative flux fields on original polygonal macrofaces.

PolyhedralRADSolution dataclass

Broken tetrahedral physical fields with their original polygonal skeleton.

local_meshes: tuple[TetraMesh, ...] property

Return each independent conforming tetrahedral local discretization.

values: tuple[FloatArray, ...] property

Return the unreconciled local scalar coefficients.

degree: int property

Return the continuous local tetrahedral polynomial degree.

evaluate(cell: int, bary: FloatArray) -> tuple[FloatArray, FloatArray]

Evaluate scalar and full physical flux -K grad(u)+beta u without averaging.

l2_error(exact: Any, order: int = 7) -> float

Integrate the scalar error through the common tetrahedral evaluator.

h1_seminorm_error(exact_gradient: Any, order: int = 7) -> float

Integrate the complete broken physical gradient error.

flux_l2_error(exact_flux: Any, order: int = 7) -> float

Integrate the full conservative physical flux error.

Physical coefficient records and norms, independent of method solver dispatch.

These records interpret explicitly assembled coefficient vectors in their executed finite-element bases. Construction performs no PDE solve, condensation or solver selection. Named FieldDefinition views provide the general-purpose field API; these records additionally supply established physical diagnostics.

DarcySolution dataclass

Broken pressure and conservative skeleton flux of a Darcy solve.

Primal pressure coefficients are continuous Pk nodal values on each macrocell. Mixed pressure coefficients are P0 cell values and the flux is RT0 conforming, with integrated face DOFs. For the primal formulation, flux stores samples of -K grad(p) at fine-cell centroids; these are not piecewise-constant coefficients when the degree exceeds one or K varies. Error norms evaluate the full field at quadrature points. Raw primal flux is generally not H(div)-conforming.

l2_error(exact: Any, order: int = 5) -> float

Integrate pressure error with independent higher-order quadrature.

flux_l2_error(exact: Any, order: int = 5) -> float

Integrate physical flux error; primal flux is evaluated as -K grad p.

conservation_residuals(order: int | None = None) -> FloatArray

Return macro flux minus source, using assembly quadrature by default.

Supply a higher order to measure source integration error separately.

fine_conservation_residuals() -> tuple[FloatArray, ...]

Return RT0 cellwise mass defects; reject raw primal flux diagnostics.

Darcy3DSolution dataclass

Broken tetrahedral pressure and physical gradient flux with conservative trace.

flux evaluates -K grad(p) and is generally not H(div)-conforming. Macro conservation refers to hybrid.trace, not this raw gradient field.

evaluate(cell: int, bary: FloatArray) -> tuple[FloatArray, FloatArray]

Evaluate pressure and physical flux at common fine-cell barycentric points.

l2_error(exact: Any, order: int = 6) -> float

Integrate the broken pressure error with independently selected positive quadrature.

flux_l2_error(exact: Any, order: int = 6) -> float

Integrate the full physical flux, including P2 gradient and variable diffusion.

conservation_residuals(order: int | None = None) -> FloatArray

Return outward skeletal flux minus integrated source in every macrocell.

QuadrilateralDarcySolution dataclass

Broken continuous-Qk pressure and conservative macro normal-flux trace.

flux stores samples of the raw physical field −K grad p at fine-cell centers. It is generally not H(div)-conforming. evaluate preserves distinct values on neighboring macrocells, without averaging.

evaluate(cell: int, points: Any) -> tuple[FloatArray, FloatArray]

Sample pressure and physical flux inside one specified macrocell.

At fine-cell interfaces the cell on the positive coordinate side is selected, except on the outer boundary. No interpolation across a permeability jump or a macroface is performed.

l2_error(exact: Any, order: int = 6) -> float

Integrate the pressure L2 error with independently chosen quadrature.

flux_l2_error(exact: Any, order: int = 6) -> float

Integrate the raw physical-flux L2 error with independent quadrature.

conservation_residuals(order: int | None = None) -> FloatArray

Return integrated macro trace outflow minus volume source per cell.

RTDarcySolution dataclass

Locally H(div)-conforming RTm flux and discontinuous nodal Pm pressure.

Mathematical degree m>=0 corresponds to Basix RT element degree m+1. MHM traces prescribe physical normal flux, while classical solutions use a globally conforming fine mesh. The latter have no skeletal multiplier.

l2_error(exact: Any, order: int = 6) -> float

Integrate the discontinuous pressure error without centroidal substitution.

flux_l2_error(exact: Any, order: int = 6) -> float

Integrate the complete physical H(div) vector error.

divergence_l2_error(exact: Any, order: int = 6) -> float

Integrate the full divergence error, distinguishing projection from pointwise balance.

fine_equilibrium_residuals() -> tuple[FloatArray, ...]

Return every DG-Pm moment of div(q)-f on each fine triangle.

fine_conservation_residuals() -> tuple[FloatArray, ...]

Return integrated fine-cell flux/source imbalance via the partition of unity.

conservation_residuals() -> FloatArray

Sum fine-cell physical balances over each local mesh/macrocell.

normal_flux_residuals() -> tuple[FloatArray, ...]

Compare all local exterior RT normal moments with the physical MHM trace.

BDMDarcySolution dataclass

Conforming BDM(k,n) flux and complete discontinuous pressure from a MHM solve.

Flux stores integrated normal moments and cell moments as specified in pymhm.fem.hdiv.bdm_family. The default BDM2/P1 uses the equivalent coordinates in pymhm.fem.hdiv.bdm. Pressure has degree k+n-1 and cardinal coefficients. The skeletal multiplier is the physical flux q.n in the macro orientation.

l2_error(exact: Any, order: int = 5) -> float

Integrate broken pressure error against an analytical pressure.

flux_l2_error(exact: Any, order: int = 5) -> float

Integrate physical BDM flux error without gradient recovery or smoothing.

divergence_l2_error(exact: Any, order: int = 5) -> float

Integrate divergence error; exact=source measures strong equilibrium error.

fine_equilibrium_residuals() -> tuple[FloatArray, ...]

Return all complete pressure moments of div(q)-f in every fine triangle.

fine_conservation_residuals() -> tuple[FloatArray, ...]

Return integrated div(q)-f over each fine cell, using assembly quadrature.

conservation_residuals() -> FloatArray

Return macro flux minus source integrals, with the signed skeleton flux.

normal_flux_residuals() -> tuple[FloatArray, ...]

Return all boundary normal-moment differences between BDM flux and skeleton.

TensorRTDarcySolution dataclass

Enriched rectangular RT flux, modal Q_s pressure and physical skeleton flux.

evaluate(cell: int, points: FloatArray) -> tuple[FloatArray, FloatArray, FloatArray]

Evaluate pressure, physical flux and divergence on every local rectangle.

errors(pressure: Any, flux: Any, divergence: Any, order: int = 8) -> dict[str, float]

Integrate three independent physical L2 errors without smoothing interfaces.

equilibrium_residuals() -> tuple[FloatArray, ...]

Return all Q_s moments of div(q)-f in each local fine cell.

normal_flux_residuals() -> tuple[FloatArray, ...]

Return all fine-boundary moments of q.n minus the represented macro trace.

Mixed3DDarcySolution dataclass

Affine H(div) flux and discontinuous pressure with their MHM skeleton.

evaluate(cell: int, points: FloatArray) -> tuple[FloatArray, FloatArray, FloatArray]

Evaluate pressure, physical flux and divergence in every local cell.

errors(pressure: Any, flux: Any, order: int = 6) -> dict[str, float]

Integrate physical pressure/vector-flux L2 errors with positive quadrature.

equilibrium_residuals(order: int = 6) -> tuple[FloatArray, ...]

Return every pressure-tested fine-cell divergence/source defect.

VectorSolution dataclass

Reconstructed velocity/displacement and optional P1 pressure fields.

l2_error(exact: Any, order: int = 5) -> float

Integrate the error in velocity or displacement.

pressure_l2_error(exact: Any, order: int = 5) -> float

Integrate pressure error with the same global gauge as the exact field.

divergence_l2() -> float

Measure the pointwise divergence norm of the reconstructed vector field.

ScalarSolution dataclass

Broken Pk scalar field reconstructed from a hybrid system.

l2_error(exact: Any, order: int = 5) -> float

Integrate scalar error using quadrature independent of assembly.

RAD3DSolution dataclass

Broken tetrahedral scalar field and full conservative physical flux.

evaluate returns u and -K grad(u)+beta*u. This physical flux differs from the skeletal Robin multiplier by beta*u/2.

evaluate(cell: int, bary: FloatArray) -> tuple[FloatArray, FloatArray]

Evaluate scalar and physical flux without averaging across macro interfaces.

l2_error(exact: Any, order: int = 7) -> float

Integrate the scalar error with a positive tetrahedral rule.

h1_seminorm_error(exact_gradient: Any, order: int = 7) -> float

Integrate the complete broken physical gradient error.

flux_l2_error(exact_flux: Any, order: int = 7) -> float

Integrate the complete conservative physical flux error.

Flow3DSolution dataclass

Broken velocity, pressure and grad-grad pseudostress on tetrahedral local meshes.

The scalar skeleton supplies face geometry and scalar modes. Its hybrid trace interleaves three canonical negative-traction coefficients per mode. Velocity and pressure are continuous only inside each macrocell. The raw pseudostress is not claimed to be globally H(div)-conforming.

evaluate(cell: int, bary: FloatArray) -> tuple[FloatArray, FloatArray]

Evaluate one-sided velocity and pressure on all fine tetrahedra of a macrocell.

gradient(cell: int, bary: FloatArray) -> FloatArray

Evaluate grad(u)[component, derivative] without averaging macro interfaces.

pseudostress(cell: int, bary: FloatArray) -> FloatArray

Return -nugrad(u)+pI+u tensor beta/2, whose normal is the MHM multiplier.

l2_error(exact: Any, order: int = 7) -> float

Return the complete broken velocity L2 error.

pressure_l2_error(exact: Any, order: int = 7) -> float

Return pressure L2 error with the explicitly imposed physical gauge.

h1_seminorm_error(exact_gradient: Any, order: int = 7) -> float

Return the complete broken velocity-gradient L2 error.

divergence_l2(order: int = 7) -> float

Integrate the raw pointwise velocity divergence; no H(div) recovery is implied.

ElasticitySolution dataclass

Bases: VectorSolution

Displacement, Herrmann pressure and physical Cauchy-stress reconstruction.

gradient(cell: int, bary: FloatArray) -> FloatArray

Evaluate the broken displacement gradient, indexed fine cell/point/i/j.

stress(cell: int, bary: FloatArray) -> FloatArray

Evaluate symmetric Cauchy stress using pressure without lambda cancellation.

h1_seminorm_error(exact_gradient: Any, order: int = 6) -> float

Integrate the full broken displacement-gradient error, not the strain norm.

stress_l2_error(exact_stress: Any, order: int = 6) -> float

Integrate the Frobenius error of the full symmetric Cauchy stress.

compressibility_l2(order: int = 6) -> float

Measure div(u)+p/lambda without asserting pointwise satisfaction.

GaLS3DSolution dataclass

Displacement, Herrmann pressure and raw symmetric Cauchy stress in three dimensions.

evaluate(cell: int, bary: FloatArray) -> tuple[FloatArray, FloatArray]

Evaluate one-sided displacement and pressure on the local tetrahedra.

gradient(cell: int, bary: FloatArray) -> FloatArray

Return the broken displacement gradient indexed component then derivative.

stress(cell: int, bary: FloatArray) -> FloatArray

Return 2muepsilon(u)-p*I without multiplying lambda by a small divergence.

l2_error(exact: Any, order: int = 7) -> float

Integrate the displacement L2 error.

pressure_l2_error(exact: Any, order: int = 7) -> float

Integrate physical Herrmann-pressure error with the imposed mean convention.

h1_seminorm_error(exact_gradient: Any, order: int = 7) -> float

Integrate the full broken displacement-gradient error.

stress_l2_error(exact_stress: Any, order: int = 7) -> float

Integrate the complete symmetric Cauchy-stress Frobenius error.

compressibility_l2(order: int = 7) -> float

Measure div(u)+p/lambda in physical L2, including zero inverse lambda at infinity.

MHSolution dataclass

Broken pressure and modified Robin multiplier of the elliptic MH method.

hybrid.trace represents (-K grad(p)-p sigma).n in the globally oriented skeleton basis. Use normal_flux for the physical one-sided outward flux lambda+p sigma.n. Raw volume fluxes are -K grad(p). These distinctions prevent using the Robin multiplier as a conservative Darcy trace.

global_coefficients: FloatArray property

Return Robin lambda followed by pressure on sorted Neumann faces.

These coefficients satisfy global_matrix/global_rhs before any mean augmentation. The system attribute retains the underlying Robin condensation, whose response objects reconstruct the volume pressure.

l2_error(exact: Any, order: int = 8) -> float

Integrate pressure error by independent physical quadrature.

flux_l2_error(exact: Any, order: int = 8) -> float

Integrate the raw physical Darcy flux error, not the Robin multiplier error.

normal_flux(cell: int, face: int, parameter: Any) -> FloatArray

Evaluate outward physical flux on one incident side of a macroface.

The Robin multiplier is shared with opposite orientations. Its added pressure trace is one-sided; pointwise physical-flux continuity is not implied when the discrete pressure jumps.

conservation_residuals() -> FloatArray

Return integral(lambda+p sigma.n)-integral(f) for every macrocell.

MH3DSolution dataclass

Tetrahedral MH pressure, Robin multiplier and physical boundary diagnostics.

The multiplier is (q-p sigma).n_global, with sigma=nu(x-origin)/3. Raw volume flux is q=-K grad(p); normal_flux_moments restores p sigma.n. The Neumann boundary extension is symmetric indefinite, even though the local Robin matrices and the Dirichlet Schur operator are positive definite.

global_coefficients: FloatArray property

Order Robin lambda before auxiliary pressures on sorted Neumann faces.

evaluate(cell: int, bary: FloatArray) -> tuple[FloatArray, FloatArray]

Evaluate the full pressure and physical flux at fine-cell barycentric points.

l2_error(exact: Any, order: int = 6) -> float

Integrate the broken pressure error using an independent volume rule.

flux_l2_error(exact: Any, order: int = 6) -> float

Integrate the raw physical flux error, not the Robin multiplier error.

normal_flux_moments(cell: int, face: int) -> FloatArray

Integrate outward physical flux against all conormal modes on one side.

conservation_residuals() -> FloatArray

Return integrated outward physical flux minus source in every macrocell.

MH2MSolution dataclass

Pressure trace, broken local pressure, and outward physical flux moments.

conormal stores lambda=A grad(p).n separately on each macrocell; its negative is the physical normal flux. Continuity holds against Gamma test functions. Neither pointwise normal continuity nor fine-cell equilibrium follows from this weak condition. Raw fluxes are -A grad(p_h).

conservation_residuals() -> FloatArray

Return integral(q.n)-integral(f) per macrocell from conormal moments.

trace_moment_residuals() -> tuple[FloatArray, ...]

Return Lambda-tested differences between local pressure and Gamma trace.

local_equation_residuals() -> tuple[FloatArray, ...]

Return original nodal equations A p-B lambda-f, without condensation.

l2_error(exact: Any, order: int = 8) -> float

Return the broken pressure L2 error using independent quadrature.

gradient_l2_error(exact: Any, order: int = 8) -> float

Return the unweighted broken H1 seminorm error.

flux_l2_error(exact: Any, order: int = 8) -> float

Return the raw physical Darcy flux L2 error; this is not the trace error.

MH2M3DSolution dataclass

Continuous pressure trace and reconstructed broken tetrahedral fields.

Each macrocell has independent outward conormal coefficients lambda=K grad(p).n. Their negatives are physical normal fluxes. Global continuity is tested by Gamma, not pointwise. The local complement has boundary mean zero; a global pure-Neumann gauge fixes the volume mean.

local_meshes: tuple[TetraMesh, ...] property

Return each conforming local tetrahedral partition.

evaluate(cell: int, bary: FloatArray) -> tuple[FloatArray, FloatArray]

Evaluate complete reconstructed pressure and raw physical flux.

l2_error(exact: Any, order: int = 6) -> float

Integrate the broken pressure error with independent tetrahedral quadrature.

flux_l2_error(exact: Any, order: int = 6) -> float

Integrate the raw physical flux error, keeping the full permeability tensor.

conservation_residuals() -> FloatArray

Return integrated outward physical conormal flux minus source per macrocell.

trace_moment_residuals() -> tuple[FloatArray, ...]

Return Lambda-tested differences of the local pressure and Gamma trace.

local_equation_residuals() -> tuple[FloatArray, ...]

Return original nodal equations A p-B lambda-f before condensation.

MsHHOLocal dataclass

One constrained Galerkin lift and its represented local moment operator.

energy is R.T A R, retaining the represented assembly's small antisymmetry. For the exactly symmetric diffusion form it is the energy Hessian. Projecting this matrix to its symmetric part would change the original finite equations.

MsHHOSolution dataclass

Broken pressure fields, common face moments and represented condensed operator.

l2_error(exact: Any, order: int = 8) -> float

Integrate broken pressure error with independent quadrature.

flux_l2_error(exact: Any, order: int = 8) -> float

Integrate the physical raw flux -A grad(u); no H(div) claim is made.

MsHHO3DSolution dataclass

Bases: MsHHOSolution

Broken tetrahedral pressure reconstructions with original-macroface moments.

l2_error(exact: Any, order: int = 6) -> float

Integrate pressure error in physical volume using independent quadrature.

flux_l2_error(exact: Any, order: int = 6) -> float

Integrate the physical raw flux -A grad(p), without an H(div) assertion.

PGMHMSolution dataclass

Base and enriched Darcy fields of the residual-based Petrov-Galerkin method.

pressure is equation (31); enriched_pressure is equation (34). hybrid.trace stores the unenriched physical flux multiplier. Physical macro conservation requires normal_flux(..., enriched=True). Both volume flux fields are raw gradients, not H(div) reconstructions.

l2_error(exact: Any, order: int = 8, *, enriched: bool = False) -> float

Integrate base or enriched pressure error in the physical L2 norm.

flux_l2_error(exact: Any, order: int = 8, *, enriched: bool = False) -> float

Integrate -K grad(p) error with the selected base or enriched pressure.

normal_flux(cell: int, face: int, parameter: Any, *, enriched: bool = True) -> FloatArray

Evaluate one-sided outward flux, including the residual enrichment by default.

conservation_residuals(*, enriched: bool = True) -> FloatArray

Return integral(q.n)-integral(f); only the enriched multiplier conserves macros.