CorePotts API Reference

Scientific category for nonconservative proposal drives.

Scientific category for conservative Hamiltonian terms.

AbstractEvent

The base type for native engine events in the Potts simulation. Events derived from AbstractEvent can be integrated directly into the PottsParameters and evaluated as part of the native sweep loop (Phase 6 of an MCS step), avoiding CPU/GPU synchronization overheads that arise when using standard SciML DiscreteCallbacks.

Any custom event should subtype AbstractEvent and provide a corresponding method for: CorePotts.evaluate_event!(evt, u, p, cache, t, deps) which launches the event asynchronously. KernelAbstractions 0.9 orders launches on the backend; the return value is nothing and host observation is handled separately.

Scientific category for pure hard admissibility constraints.

Scientific category for non-Hamiltonian transition-rate modifiers.

Scientific category for stateful non-equilibrium mechanical work.

PottsState{Grid, CellData}

The mutable state vector u for a Cellular Potts Model simulation. Contains the grid, cell properties, and cell ID tracking structures.

Open scientific proposal-law family, independent of algorithm scheduling.

Marker for a versioned mapping from semantic random addresses to bits and distributions.

Open family for ordered one-proposal-at-a-time scientific algorithms.

Pure, structured inputs to a named acceptance law.

The active finite cells in the common pre-lifecycle snapshot.

AdhesionPenalty(J_matrix)

Calculates the differential adhesion (surface tension) between cells of different types, and between cells and the medium. Drives cell sorting and morphological clustering.

Programmatically inspectable scientific contract for one named algorithm process.

Use the selected CPM algorithm temperature as a visible mechanical-noise default.

Conjunction of allocation-free lifecycle triggers evaluated against one snapshot.

AsymmetricReset(parent_value, child_value) <: InheritanceRule

The parent has the property set to parent_value and the child has the property set to child_value.

Assign explicit parent and child values after division.

Run at an explicit, canonical collection of positive integer-MCS boundaries.

Negative and positive face behavior for one Cartesian axis.

Host-side declaration of capabilities which have been implemented and qualified.

Exact number of outward unlike-owner incidences.

One cached finite-cell boundary measure with a complete metric/relation identity.

CartesianDomain(dims; spacing, boundaries, obstacles)

Host scientific description of a rectangular ownership domain. obstacles is an iterable of site => MediumOwner(...) pairs. Obstacle sites remain in rectangular storage but are excluded from the mutable recipient set.

Device-safe domain metadata required to interpret compiled storage.

Validated immutable categorical cumulative weights suitable for compiled execution.

Validated fixed finite-cell capacity; this is not the active cell count.

A lifecycle or initialization request exceeded fixed finite-cell capacity.

Immutable descriptor plus backend-adaptable cell-centered scalar field storage.

Generation counter that distinguishes reuse of one finite-cell slot.

Public reusable finite-cell identity. Zero and negative values are never valid cell IDs.

A compile-time cell-property reference with no device-side Symbol field.

Internal fixed-capacity storage slot identity for a finite cell.

Read-only compiled finite-cell-type identity; user-facing types remain symbolic.

Restrict a lifecycle event to one immutable set of finite cell-type IDs.

CheckerboardMetropolis(; sampler=MetropolisSampler(), sweeps_per_step=10, active_fraction=0.1f0, T=1.0f0)

A deterministic-stochastic checkerboard engine. It calculates the mathematically perfect graph coloring for the topology to completely remove the random lottery and maximize GPU utilization while remaining mathematically equivalent.

Parallel color-sweep CPM with snapshot evaluation and deterministic conflicts.

Device-resident schedule and candidate storage for one realized-domain coloring.

Native nonconservative donor-to-recipient chemotaxis log bias.

ChemotaxisPenalty(lambdas, chemical_field)

Biases cell membrane extensions up (or down) a pre-computed spatial chemical gradient.

Clone <: InheritanceRule

The child cell receives an exact copy of the parent cell's property (e.g. target_volume).

Copy one authoritative parent value to both binary descendants.

An ownership relation leaving this face realizes no edge.

Device-adaptable mutable-site and immutable-owner domain storage.

Backend-adaptable structure-of-arrays lowering of logical site ownership.

Host descriptor paired with compiled storage; kernels receive execution_storage(state).

CompiledRule{F, S} <: UpdateRule

A highly optimized native Julia closure rule generated by the @rule macro.

Type Parameters

• F: The type of the native function closure (cell_data, cell_id, ctx) -> ...
• S: The type of the spatial metadata tuple (ContactArea(...), ...)

Fields

• func::F: The native function to execute on the GPU.
• spatial_rules::S: The tuple of spatial extraction rules required by this closure.

Compiled state, ownership domain, derived caches, and device-safe retirement defaults.

Host-only information required to reconstruct and validate compiled state.

Device-valid structure-of-arrays storage. This is the only adaptable state boundary.

Stable provenance for a scientific component or extension request.

Preallocated exact connectivity traversal storage for one work item at a time.

An isbits constant property initializer suitable for compiled state.

A host-side parameterization which leaves an already concrete component set unchanged.

Reset both descendant forces to their post-commit constitutive means.

Explicit coordinates owned by one provisional finite cell.

Union-free result of recipient/direction selection, including proposal-budget no-ops.

CopyProposal

Immutable complete local ownership-copy proposal. recipient is overwritten by gaining; donor is the neighboring site carrying that owner. It is intentionally independent of backend storage.

Dense nonnegative provisional-cell labels with explicit label-to-type declarations.

Explicit ownership for expert backend-resident initial state.

Reusable exact distinct-cell set storage for CPU and device rule evaluation.

Context supplied to a schema-owned binary division policy.

Complete parent/child result returned by a division policy.

A validated request to transfer selected parent-owned sites to one daughter cell.

Scalar geometry data for labeling one parent-owned site into a descendant region.

EventBuilder

A programmatic builder for constructing events with strongly-typed rules.

Run at every positive integer-MCS lifecycle boundary.

Immutable execution policy and backend paired with separately mutable instrumentation.

ExtendedMooreTopology{N, R}

An extended periodic N-dimensional Moore neighborhood of radius R.

ExtendedVonNeumannTopology{N, R}

An extended periodic N-dimensional Von Neumann neighborhood of radius R.

Globally integrable occupancy coupling to one immutable field snapshot.

An immutable medium or wall domain beyond one Cartesian face.

Mechanical-noise scale independent of the CPM acceptance temperature.

FlexibilityTrait

Traits indicating whether a physical property or penalty is rigid (type-coupled) or flexible (per-cell and dynamically writable).

Non-equilibrium per-cell tension with an exact frozen-surface OU transition.

Non-equilibrium per-cell pressure with an exact frozen-volume OU transition.

FocalPointSpringPenalty(lambdas, target_lengths, connectivity)

Models strong mechanical junctions (springs) between the centers of mass of specific cells. Useful for modeling epithelial sheets or rigid tissue structures.

One global model target at a lifecycle boundary.

HDF5Backend(path::String)

Streams the simulation out-of-core to an HDF5 dataset on disk. Requires using HDF5.

HSTFocalPointPenalty(lambdas, connectivity)

A thermodynamically consistent (fluctuating force) version of the focal point spring.

HSTLengthPenalty(lambdas)

Constrains the major axis length of a cell, inducing elongation and polarity.

HSTSurfaceAreaPenalty(lambdas; eta=1.0f0)

A hydrostatic formulation of the surface area constraint using fluctuating membrane tensions. Prevents cells from fragmenting or infinitely stretching.

HSTVolumePenalty(lambdas; eta=1.0f0)

A hydrostatic formulation of the volume constraint. Uses a fluctuating internal pressure p for each cell instead of a rigid quadratic constraint, allowing for thermodynamic detailed balance.

InheritAdd(value) <: InheritanceRule

Both parent and child have value added to their property.

InheritMultiply(value) <: InheritanceRule

Both parent and child have their property multiplied by value.

A provisional finite-cell raster with its declared compiled cell type.

Property overrides for one declared provisional cell, independent of its geometry layout.

Compact requirements declared by an initialization layout.

A raster owned by one declared conceptual medium domain.

IntrinsicCheckerboardMetropolis(; sampler=MetropolisSampler(), sweeps_per_step=10, active_fraction=0.1f0, T=1.0f0)

The flagship, hardware-accelerated Monte Carlo engine of the Potts.jl ecosystem.

Standard GPU Cellular Potts Models suffer from the Global Volume Paradox: maintaining exact thermodynamics (Detailed Balance) requires perfectly tracking the volume of every cell. Global atomics cause massive memory contention, while removing them breaks the physics.

IntrinsicCheckerboardMetropolis solves this paradox by utilizing branchless SIMT Subgroup Reductions via KernelIntrinsics.jl. It uses low-level hardware intrinsics (like NVIDIA's PTX @shfl and @match, or Apple Silicon's air.simd_ballot) to instantaneously aggregate volume changes inside the hardware registers of the 32-thread warp. A single elected "Leader" thread then performs an O(1) atomic write to global memory.

Properties

• Mathematically Exact: Perfectly preserves rigorous Detailed Balance.
• Maximally Parallel: Completely eliminates global memory locking and atomic contention serialization.
• Hardware Native: Compiles directly down to native Metal shading language (Apple) or PTX (NVIDIA) subgroup instructions.

Euclidean lattice ball (disk in 2D, sphere in 3D).

Axis-aligned lattice box described by an integer half-width per axis.

LegacyPottsIntegrator{uType, pType, tType, algType, cacheType, OptsType}

The active simulation state, holding u, p, t, alg, and the cache. Provides SciML-compatible continuous integration for the Potts.

LegacyPottsProblem{uType, tType, pType} <: AbstractPottsProblem

A SciML-compatible problem definition for a Cellular Potts Model.

Fields

• u0: The initial state (PottsState).
• tspan: A tuple (t_start, t_end) defining the simulation duration in Monte Carlo steps.
• p: The simulation parameters (PottsParameters).

LegacyPottsSolution{T, P, A} <: SciMLBase.AbstractTimeseriesSolution

The result of a completed simulation. Contains the saved grid states and cell property states over time. Accessible like an array: sol[i] returns the state at time sol.t[i].

One identity-changing claim used by an explicit lifecycle conflict resolver.

Typed composition of one lifecycle target, schedule, trigger, and effect.

LocalNeuralPenalty{M, W, S}

A Neural Penalty that evaluates an allocation-free Neural Network (e.g. from SimpleChains.jl) over a localized spatial patch.

Result of one logical ownership-copy transaction.

Stable result of initialization finalization, including provisional-to-runtime evidence.

LogicalPottsState

Final CPU logical state boundary. The underscored fields are deliberately storage details; callers use the accessors below so this state can later be lowered to backend-specific representations without changing scientific meaning.

Thrown when a logical state violates one or more accepted state-model invariants.

Topology-calibrated parallel lottery CPM with equal per-site expected activation.

Compiled realized-graph schedule and reusable storage for LotteryCPM.

Published axis-calibrated correction table from Magno et al., version 1.

MajorAxisOrientation <: DivisionOrientation

Cell division occurs perpendicular to the cell's major (longest) axis.

Conceptual medium-domain identity, distinct from finite-cell identities.

Finite static mapping from conceptual medium owner IDs to cell-type IDs.

MemoryBackend()

The default out-of-core data saving backend. Pushes grid and cell_data into an array in RAM.

MinorAxisOrientation <: DivisionOrientation

Cell division occurs perpendicular to the cell's minor (shortest) axis.

MooreTopology{N}

A standard periodic N-dimensional Moore neighborhood (8-connected in 2D, 26-connected in 3D).

Conventional neighboring-owner copy proposal used by the current CPM algorithms.

Zero-storage marker for models without an exact connectivity constraint.

NoFluxExtendedMooreTopology{N, R}

An extended N-dimensional Moore neighborhood of radius R with no-flux boundaries.

NoFluxExtendedVonNeumannTopology{N, R}

An extended N-dimensional Von Neumann neighborhood of radius R with no-flux boundaries.

NoFluxMooreTopology{N}

An N-dimensional Moore neighborhood with rigid, non-periodic (no-flux) boundaries.

NoFluxVonNeumannTopology{N}

An N-dimensional Von Neumann neighborhood with rigid, non-periodic (no-flux) boundaries.

Zero-storage marker used when no center-dependent component is compiled.

Physical boundary estimate from the square-order-4 or cubic-order-6 raw kernel.

Typed numerical choices that belong to scientific model identity.

Derived occupancy data reconstructed exclusively from authoritative lattice ownership.

Run at exactly one positive integer-MCS boundary.

OwnerRef

Compact, isbits logical owner identity for one realized lattice site. The tag makes finite-cell and medium-domain identity disjoint even when their numeric identifiers are equal. It is a host representation in this phase; a future device lowering may use a different encoding while exposing the same accessors.

Finite-cell property plus explicit medium-domain scalar values.

Exact finite-cell and conceptual-medium occupancy tracker.

ParallelMetropolis(; sampler=MetropolisSampler(), sweeps_per_step=10, active_fraction=0.1f0, T=1.0f0)

The solver algorithm for LegacyPottsProblems. Specifies how Monte Carlo Sweeps are executed.

Keyword Arguments

• sampler: The sampling strategy (default MetropolisSampler()).
• sweeps_per_step: How many Monte Carlo Sweeps equal one simulation time unit (default 10).
• active_fraction: Fraction of the grid proposed for updates per sweep (default 0.1).
• T: The computational temperature regulating membrane fluctuation (default 1.0).

A paired axis wraps through the opposite face.

Run from start every period MCS, optionally through an inclusive stop.

First production candidate: Philox4x32 with ten rounds and Potts address packing v1.

Morpheus-style non-Hamiltonian positive yield barrier.

PottsCache{N}

The algorithmic workspace and cache used during Monte Carlo execution.

Explicit thread-safe cache for trajectory-free compilation metadata.

PottsModel(proposal_relation, boundary_tracker; components, parameters, ...)

Reusable scientific meaning for the Phase 9 interface. A custom parameterization is an ordinary typed callable which maps the problem's concrete parameter container to a ScientificComponentSet on the host before device adaptation.

PottsParameters{Topo, P, Tr, Ev}

The physics definition parameters p for a Cellular Potts Model simulation.

Immutable portable experiment definition.

PottsTrainingCache{State, Params, Alg}

Holds the persistent MCMC chains used for negative sampling during Contrastive Divergence training.

Read-only-by-contract view observed by every trigger at one completed MCS boundary.

Exact global connectedness constraint; fragmentation remains legal when omitted.

Clone an intensive mechanical state into both descendants.

Preserve one property value across a compatible type transition.

Immutable, provenance-aware declaration for one logical fixed-capacity property.

Fixed-capacity columns compiled from a PropertySchema.

Stable layout-time identity; it is not a requested runtime cell ID.

Ordinary conservative finite-cell boundary Hamiltonian.

Conservative finite-cell energy strength * (major_axis_rms - target)^2.

Native conservative finite-cell volume Hamiltonian lambda * (V - target)^2.

RNGAddress

Complete scheduling-independent coordinates for one block of four random UInt32 values. Valid addresses pack injectively into the Philox 128-bit counter for a fixed master seed and cell generation. invocation is the local retry/invocation coordinate; draw distinguishes lexical or algorithmic draws owned by one operation.

Semantic identity domain for an addressed random operation.

Stable 128-bit identity for one extension-owned stochastic namespace.

Stable named stream families. Numeric values are part of the RNG contract.

RandomNormal(mean, std) <: InheritanceRule

Both parent and child have their property drawn from a normal distribution.

RandomOrientation <: DivisionOrientation

Cell division occurs along a completely random axis.

RandomUniform(min, max) <: InheritanceRule

Both parent and child have their property drawn from a uniform distribution [min, max].

One role-filtered realized neighbor. Fixed owners are carried without a union field.

Mark a derived value for reconstruction after transition.

Symmetric unordered contact Hamiltonian for the scalar reference engine.

Scientific inputs consumed by the first sequential reference vertical slice.

Quadratic finite-cell volume Hamiltonian for the scalar reference engine.

Reject a site claimed by distinct semantic owners.

Reject every target receiving more than one identity-changing claim.

Device-safe semantic version for relation canonicalization rules.

Reset(value) <: InheritanceRule

Both parent and child have the property set to value.

Initialize both descendants from the property initializer.

ResetChild(value) <: InheritanceRule

The parent retains its property, but the child has the property set to value.

Preserve the parent and initialize the child from the property initializer.

Reset a retired property slot to its canonical initializer value.

Initialize one property from its schema initializer after transition.

RuleBuilder

A programmatic builder for CompiledRule objects. Ensures that the provided closure matches the expected 4-argument signature: (cell_data, cell_id, ctx, current_val) before wrapping it in a CompiledRule.

Typed backend- and dimension-level scientific capability declaration.

Typed scientific component bundle lowered once and passed unchanged to hot kernels.

Category-preserving scalar result consumed by a separately selected acceptance law.

Device-valid scientific state and immutable tracker identity passed to hot kernels.

Stable diagnostic for one incomplete scientific extension.

Report returned by the public category conformance helpers.

Accounting for one completed normalized MCS.

One immutable pre-copy view shared by every component in a proposal evaluation.

Pure tracker delta staged from one common pre-copy snapshot.

Device-adaptable tracker arrays owned by one compiled scientific model.

Conventional modified-Metropolis CPM with exactly N selections per MCS.

Metropolis-Hastings sequential sampler for capability-qualified equilibrium models.

SequentialMetropolis(; sampler=MetropolisSampler(), sweeps_per_step=10, active_fraction=0.1f0, T=1.0f0)

A strictly sequential CPU algorithm that processes sites randomly one-by-one. No parallel contention.

Conventional modified-Metropolis sequential reference algorithm.

Bounded, canonical sequential rejection placement of one shared shape family.

One explicitly centered procedural cell shape.

SnapshotScientificAccess(relations=(); cell_wide=false, private_workspace=false)

Auditable access trait for a component evaluated against a common immutable subround snapshot. relations contains every realized spatial relation whose simultaneous recipient writes could interact. cell_wide declares dependence on mutable finite-cell state, and private_workspace requires proposal-private scratch storage before parallel execution can be qualified.

Split(fraction=0.5f0) <: InheritanceRule

The parent cell's property is split between the parent and child according to the fraction.

Conservatively split a numeric value, assigning child_fraction to the child.

Select the unique greatest explicit claim priority and reject a tied winner.

Select the unique greatest explicit priority for each target; reject priority ties.

Immutable ownership-plus-tracker transaction; construction performs no writes.

Canonical, isbits Cartesian relation whose direction IDs are semantic.

Redraw both descendant forces from their post-commit stationary laws.

SurfaceAreaTracker

A global state tracker that automatically tracks the surface area (number of dissimilar neighbor interactions) for each cell dynamically as the grid is updated.

Reusable staging buffers for snapshot/evaluate/commit algorithms.

Context supplied to a schema-owned type-transition policy.

Uniform injection of labeled one-site seeds into eligible, unreserved sites.

Symmetric unordered contact Hamiltonian over one explicit contact relation.

Explicitly reject division when this property is present.

Host-side trait for a component not yet qualified for deterministic parallel snapshots.

Explicitly reject a type transition when this property is present.

Unwrapped coordinate moments for an explicit connected finite-cell subset.

VectorOrientation(nx, ny, nz) <: DivisionOrientation

Cell division occurs perpendicular to the specified normal vector.

VolumePenalty(lambdas)

The classic cellular volume constraint. Acts as a harmonic spring, penalizing deviations from a cell's target_volume according to its type-specific lambda.

VolumeThresholdTrigger(multiplier=2.0)

A callable trigger that evaluates to true when a cell's current volume is greater than or equal to multiplier * target_volume. Used to trigger mitosis.

VolumeTracker

A global state tracker that automatically tracks the volume (number of grid sites) belonging to each cell without requiring O(N) recalculations per step.

VonNeumannTopology{N}

A standard periodic N-dimensional Von Neumann neighborhood (4-connected in 2D, 6-connected in 3D).

Sum of explicit relation weights over outward unlike-owner incidences.

ZarrBackend(path::String)

Streams the simulation out-of-core to a Zarr dataset on disk. Requires using Zarr.

SciMLBase.solve!(integrator::LegacyPottsIntegrator)

In-place execution of the Potts simulation. Steps the integrator forward in time until it reaches the end of the problem's timespan. Useful for manual loop control and avoiding memory reallocation.

SciMLBase.solve(prob::LegacyPottsProblem, alg::AbstractPottsAlgorithm, args...; kwargs...)

Standard out-of-place execution interface. Dynamically initializes a new LegacyPottsIntegrator, allocates engine structures, executes the full simulation, and returns a LegacyPottsSolution.

Dispatch one complete MCS through the algorithm-owned open hook.

Logical owner reference for one finite cell.

Logical owner reference for one conceptual medium domain.

build_cell_data(grid, N_cells; custom_fields...)

Allocates and constructs a StructArray on the same backend as grid (CPU or GPU) to hold macroscopic cell properties like :volumes, :target_volumes, :cell_types, :pressures, etc.

reset_hst_fields_after_division!(engine, pen::AbstractHSTPenalty)

Resets the stochastic auxiliary field for all live cells to its thermodynamic mean immediately after a mitosis event, preventing O(1/η) MCS transients.

Exact major-axis RMS extent derived from an unwrapped covariance tensor.

Deterministic greedy coloring of one canonical realized conflict graph.

Canonical CSR form of the union of realized mutable-site conflict relations.

Acceptance law selected by an ordered scientific algorithm.

Move compiled arrays while deliberately retaining the host-only descriptor.

Instrumented initialization-time adaptation of the compiled storage boundary.

Host-only algorithm/component preflight; downstream algorithms extend this by dispatch.

Inspectable scientific algorithm guarantee profile; extensions implement this method.

Return the immutable scientific guarantee profile owned by this integrator's algorithm.

apply_division_batch(state, requests; minimum_daughter_volume=1)

Validate all requested geometries from one snapshot, preflight the full fixed-capacity batch, then commit deterministic parent/child assignments to a private candidate. Capacity failure leaves the input state untouched; slots retired in this MCS are absent from _available_lifecycle_slots until release_retired_slots is called at the next boundary.

Return only capabilities CorePotts is prepared to claim for this backend.

Portable Bernoulli variate with exact boundary behavior.

Unbiased integer in 0:(bound - 1) using local retry-addressed rejection.

One-based categorical index from a prevalidated immutable table.

commit_copy_proposal(state, proposal; accepted=true, constraints=())

Apply one accepted typed ownership-copy proposal to a private logical-state candidate. The lattice is authoritative; derived occupancy is rebuilt and any extinct finite owner is retired immediately, while the resulting slot remains unavailable for reuse until the lifecycle boundary releases it.

Commit exactly once when accepted; rejection is a guaranteed no-write operation.

Validate and lower extension namespace identities without a runtime registry.

Complete host-side scientific metadata shared by direct CorePotts and authoring reports.

Stable semantic payload contributed to model manifests and fingerprints.

Whether a component is qualified on the selected backend capability contract.

Whether a component declares support for a model dimensionality.

construct_copy_attempt(state, domain, proposal_relation, recipient, direction; mcs, semantic_id)

Construct one conventional neighbor-site attempt. Exact transition multiplicities are counted around the recipient so Metropolis-Hastings receives complete forward/reverse proposal support.

Whether a typed device callback is due at this completed MCS.

Declared effects of a device callback; Phase 9 qualifies pure resident observation only.

Stable ordering priority for resident observations; lower values execute first.

Typed observable handles read by a device callback's bounded kernel operation.

Conservatively validate that every runtime field passed to kernels is an isbits array tree.

dispatch_kernel!(backend, kernel, args...; ndrange, workgroupsize=nothing)

KernelAbstractions 0.9 launch spelling for historical consumers. Launches are asynchronous and ordered on every supported backend. New compiled execution code uses instrumented launch! and synchronizes only through synchronize_observation!.

Open property lifecycle operations implemented by policy-value dispatch.

Open allocation-free query returning a compact descendant-region label.

Host report containing every scientific choice in one Cartesian ownership domain.

Dimensionless nonconservative log bias; extensions implement this pure method.

Open claim-emission operation into compiler-owned initialization storage.

Conservative local energy difference; extensions implement this pure method.

Evaluate every declared component against exactly one shared pre-copy snapshot.

evaluate_penalty(p::Union{FocalPointSpringPenalty, HSTFocalPointPenalty}, ctx)

Evaluates the focal point spring penalty.

Note: To avoid the severe performance penalty of calculating the exact quadratic center-of-mass shift and resolving atan2 circular statistics for every proposed pixel flip on periodic boundaries, this function evaluates the energy using the linearized auxiliary field approximation (Force * Δx). The exact forces (and any HST stochastic noise) are computed once per cell during the sweep auxiliary step.

evaluate_trigger(evt::AbstractEvent, i::Int, cell_data, t)

Evaluates the event trigger for cell i on the device. Only called if has_device_trigger(evt) returns true. Should return a Bool.

Typed effects emitted from one event-phase snapshot; extensions implement this method.

Launch a bounded resident callback operation without materializing scientific state.

execute_step!(u::AbstractPottsState, p::PottsParameters, cache::PottsCache, alg::CheckerboardMetropolis)

Executes a single Monte Carlo Sweep (MCS) across the grid using a deterministic checkerboard algorithm.

execute_step!(u::AbstractPottsState, p::PottsParameters, cache::PottsCache, alg::ParallelMetropolis)

Executes a single Monte Carlo Sweep (MCS) across the grid using the stochastic lottery algorithm.

execute_step!(u::AbstractPottsState, p::PottsParameters, cache::PottsCache, alg::SequentialMetropolis)

Executes a single Monte Carlo Sweep (MCS) sequentially on the CPU without atomic locks.

Stable v1 operation slot for a 128-bit extension namespace; collisions are rejected.

Domain-separated trajectory seed for one extension instance.

finalize_initial_state(shape, layouts...; capacity, medium_domains, property_schema,
                       overlap_policy=RejectInitialOverlap())

Finalize open layout claims in an order-independent host pipeline: resolve overlaps, remove empty entities, assign compact runtime IDs by semantic identity, validate capacity, initialize schema properties, reconstruct derived state, and publish only an invariant-valid logical state.

get_event_args(evt::AbstractEvent, mask, u::AbstractPottsState, p::PottsParameters, cache::PottsCache, t)

Returns a tuple of arguments to be splatted into the event's kernel function. Users defining custom events must implement this method. Returning a tuple of exactly what the kernel needs prevents massive memory closures and GPU compiler crashes on Metal.jl.

Note that mask is passed directly. If your kernel requires the mask as its first argument, you must explicitly include it in the returned tuple, e.g. return (mask, u.cell_data.volumes).

If the event should not run during the current step (e.g. t % check_interval != 0), return nothing to skip kernel execution.

get_event_kernel(evt::AbstractEvent, backend, block_size)

Returns the compiled @kernel function for the given event. Users defining custom events must implement this method and return the kernel instance initialized with the backend and block_size.

get_event_ndrange(evt::AbstractEvent, mask, u)

Returns the size of the iteration space for this event's kernel. By default, this sweeps over all cells (length(mask)).

Canonical unordered interface measure between two explicit owner filters.

has_device_trigger(evt::AbstractEvent)

Returns true if this event provides a device-side evaluate_trigger function that should be evaluated in the unified event kernel to generate a boolean mask. By default, this is false.

Immediately remove one cell by replacing all of its sites with a declared medium domain.

init_scientific(state, proposal_relation, components, algorithm; seed, plan, ...)

Construct the Phase 7 scientific integrator over already compiled, backend-resident state. The seed is execution state rather than algorithm configuration. No simulation work or observation sync is performed during construction.

Open construction-time requirements query for one layout.

initialize_com_anchors!(u, p, cache)

Runs the two Center-of-Mass kernels sequentially to pre-initialize the anchor coordinates. This is called exactly once per simulation during sync_cell_data! so that the fused HSTLengthPenalty kernel has valid previous-step anchors on its very first sweep.

Open initialization hook for downstream scientific algorithms.

initialize_workspace(evt::AbstractEvent, u::AbstractPottsState, topology::AbstractTopology)

Called exactly once during simulation initialization. By default, returns evt unmodified. Custom events can override this to allocate dynamic memory workspaces.

Pure hard-constraint predicate; extensions implement this method.

Allocation-free exact connectivity predicate for compiled CPU/GPU execution.

Backend-visible lattice storage for an explicit execution boundary.

Launch one device-resident staged commit without an implicit synchronization.

Open, side-effect-free trigger query for one target in one common snapshot.

Reconstruct a host snapshot from CPU storage that has no outstanding asynchronous work.

One synchronized, fully instrumented device-to-host logical observation.

Current authoritative logical state of a sequential reference integration.

Exact frozen-observable Ornstein-Uhlenbeck transition used by stable mechanics.

neighbor_cells!(workspace, state, domain, relation, owner, filter, medium_types, epoch)

Write canonical distinct finite-cell IDs into workspace.ids and return their count. epoch must be nonzero and unique for every live use of the workspace; clear seen_epochs before epoch reuse. The routine allocates nothing and is valid inside a single device work item.

Box–Muller standard normal; statistically portable because backend transcendentals may differ.

normalized_kernel_relation(Val(N); spacing)

Published square-order-4 (N == 2) or cubic-order-6 (N == 3) surface stencil. The corresponding correction factor belongs to NormalizedKernelMeasure, not to relation weights.

Raw Random123-compatible Philox4x32-10 primitive.

Open effect-planning operation. Planning must not mutate the supplied snapshot.

poisson_inversion(contract, seed, address, rate)

Exact inversion sampler for 0 ≤ rate ≤ 64. It is intentionally domain-limited rather than silently switching algorithms. Each loop iteration owns a distinct local draw address.

Separately named nonnegative rounded-normal approximation to Poisson sampling.

potts_loss(theta, cache::PottsTrainingCache, data_batch, update_fn)

The pure mathematical loss function for Persistent Contrastive Divergence EBM training. update_fn(p::PottsParameters, theta) maps the flat/ComponentArray theta back into a full PottsParameters struct. This function evaluates the global energy difference E_data - E_model. NOTE: The MCMC sampling step (execute_step!) must be run outside this function (e.g., in an Optimization.jl callback) so that AD engines do not attempt to trace it.

process_death_events!(engine)

Scans the grid for any cells whose target_volume is less than or equal to 0. These cells are killed (removed from the grid) and their IDs are recycled for future use.

process_mitosis_events!(engine; trigger=VolumeThresholdTrigger(), orientation=RandomOrientation(), inheritance_rules)

Evaluates the trigger for all active cells. For any cell where the trigger is true, the cell is divided in half according to the geometric orientation. Properties are inherited by the new daughter cell according to inheritance_rules.

Public compiled proposal-evaluation protocols implemented by category dispatch.

Proposal law selected by an algorithm; downstream algorithms may extend this method.

Recompute the derived occupancy layer from authoritative lattice ownership.

Complete tracker reconstruction from authoritative ownership; extensions implement this method.

Complete scalar Hamiltonian evaluation used to validate local deltas.

The temporary, explicitly versioned random-bit contract of the Phase 4 reference engine.

Host report preserving role, direction IDs, weights, and canonicalization version.

Release retirement results at the next integer-MCS boundary in ascending slot order.

Open family-owned repair hook after committed division and derived-state reconstruction.

required_variables(component)

Returns a NamedTuple mapping the required variables to their types for a given physics penalty or tracker.

Return winning source indices in ascending target-ID order.

Retire all zero-occupancy finite cells, reset their schema properties, and defer reuse.

Pack one valid semantic address into the exact Philox (counter0, counter1, key) input.

Return the component's conservative deterministic-parallel access declaration.

small_permutation!(destination, contract, seed, address)

Exact Fisher–Yates permutation for small scientific schedules such as checkerboard colors. The destination length is limited by the v1 draw domain; large layout permutations use a separately compiled primitive.

spawn_hypersphere!(grid, grid_dims, center, radius, cell_id)

Paints a spherical cluster of cell_id onto the grid centered at center with radius. Works in both 2D and 3D.

Advance one and only one normalized MCS through the scalar reference engine.

Complete host report for the ordinary boundary Hamiltonian and its cached measure.

sync_cell_data!(u::AbstractPottsState, p::PottsParameters, cache::PottsCache, num_cells::Int; set_targets::Bool=true)

Scans the grid and calculates the actual volumes and centroids for all cells from 1 to num_cells. If set_targets is true, sets target_volume to match the initial volume.

sync_cell_data!(grid, cell_data, num_cells)

A utility to manually count cell volumes from the grid and set them in cell_data. Sets both volumes and target_volumes to the counted value.

Minimal public energy conformance helper with representative method validation.

Supported Cartesian dimensions of a topology; extensions implement this method.

Apply one type transition atomically according to every schema property's transition policy.

Portable uniform Float32 or Float64 variate strictly inside (0, 1).

Validate that labels form exactly two nonempty binary descendant regions.

validate_closure!(closure)

Pre-flight validation to ensure the closure signature is structurally sound before we send it to the GPU. Catches errors like 3-argument vs 4-argument mismatches.

Reject self-edges, periodic aliases, ambiguous corners, and role/domain dimension mismatch.