jcm.dycore.base.DynamicalCore

class jcm.dycore.base.DynamicalCore

Protocol for a swappable dynamical-core backend.

Concrete backends subclass this and register themselves with jcm.dycore.registry.register_dycore(). The user-facing Model constructs a backend (or accepts one) and delegates every state-touching operation to it.

A backend is responsible for:

  • Carrying its own native state representation across step calls.

  • Projecting that state to and from PhysicsState so that physics packages can run on a common gridpoint layout (no spectral coefficients leak into physics).

  • Applying its own hyperdiffusion / filters as part of step. The physics-dynamics seam is purely operator-split (Lie a): the gridpoint physics_tendency is forward-Euler-added to the state and the dycore then takes one dt of dynamics.

  • Building its own terrain (orography is smoothed against the dycore’s own basis — spectral truncation for dinosaur, SE projection for pyses, …).

  • Converting a trajectory to xarray for output (the cubed-sphere → lat/lon regrid for SE backends lives here, not in the physics path).

Instance attributes:
coords: Coordinate system carrying horizontal lat/lon arrays (in the

dycore’s native shape) and the vertical level definitions. For the v2 dinosaur backend this is the dinosaur CoordinateSystem; SE backends provide a compatible adapter.

dt_seconds: The integration timestep this dycore was built for. Concrete

backends may sub-cycle internally but step advances by exactly dt_seconds (or the override passed to step).

terrain: Boundary conditions (orography, land/sea mask, SSO descriptors).

Built via build_terrain() or passed in at construction.

tracer_specs: Public mapping name -> TracerSpec declaring every

tracer the dycore should carry. Model writes this every time it is constructed (so callers who pass a pre-built dycore still get the right specs); backends read it from initial_state(), to_physics_state(), and step().

__init__()

Methods

__init__()

build_terrain(*[, source_file])

Construct a TerrainData against this dycore's basis.

initial_state(physics_state, *[, sim_time, ...])

Build the dycore's native initial state.

required_tracers_ok(specs)

Verify the dycore can carry the requested tracers.

sim_time(state)

Return the simulation-time (seconds) carried by state.

step(state, physics_tendency)

Advance the state by one dt.

to_physics_state(state)

Project the dycore's native state into a gridpoint PhysicsState.

to_xarray(predictions, times, *[, ...])

Convert a saved trajectory to an xarray.Dataset.

with_sim_time(state, sim_time)

Return a copy of state whose sim-time has been replaced.