Feature Roadmap

This roadmap summarizes the current direction for Particula feature development. It is a guide for users and contributors, not a fixed release schedule.

Current Focus

• Strategy-based physics systems: Continue standardizing dynamics modules around strategy, builder, and factory APIs.
• Runnable workflows: Make condensation, coagulation, wall loss, and related processes easier to compose in clear simulation pipelines.
• Particle and gas data containers: Complete migration from legacy facades toward explicit ParticleData and GasData containers.
• GPU process completeness: Deliver dilution, wall loss, nucleation, and fixed-slot particle management through Epic F.
• GPU-resident user workflows: Prepare backend selection and high-level simulation integration for on-deck Epic G.
• Documentation and examples: Expand practical examples that connect feature guides, theory pages, and runnable notebooks.

Planned Improvements

Dynamics Systems

• Add more high-level examples for combining condensation, coagulation, and wall loss in shared time-stepping loops.
• Improve guidance for choosing distribution types across discrete, continuous-PDF, and particle-resolved simulations.
• Continue exposing new physics models through consistent builders and factories.

Data Model Migration

• Reduce reliance on legacy ParticleRepresentation and GasSpecies facade patterns where newer data containers provide clearer state management.
• Keep migration documentation up to date as APIs stabilize.
• Identify remaining compatibility layers that can be simplified before a stable major release.
• Track details in the data-oriented design and GPU roadmap.

GPU Acceleration

• Integrate existing Warp condensation and Brownian coagulation kernels into higher-level user workflows.
• Add documented examples for GPU-resident particle simulations that avoid repeated CPU/GPU transfers.
• Define parity, performance, and fallback expectations for CPU, Warp CPU, and CUDA execution.
• Track details in the data-oriented design and GPU roadmap.

Examples and Education

• Add more end-to-end chamber simulation examples.
• Expand notebook coverage for feature systems that currently have only API documentation.
• Improve links between examples, feature guides, theory pages, and API reference material.

Epic Status

The data-oriented and GPU work is tracked as a single ordered epic sequence with explicit exit bars in the Data-Oriented Design and GPU Roadmap. Each epic targets roughly 5-10 features of 5-15 phases each; when an epic meets its exit bar, the next pending epic in the sequence becomes active.

Shipped

• Epic A: Data-Model and Numerical Foundations (ADW plan E2) — container schemas, EnvironmentData, CPU↔GPU transfer boundary, precision baseline, and stiffness recommendation. Shipped artifacts:
  • Data Containers and GPU Foundations — shipped guide for the current container, transfer-helper, and support boundary baseline
  • Data Containers example — canonical runnable entrypoint linked from the roadmap handoff notes
  • Mass Precision Recommendation Report — canonical reference for downstream dtype/schema decisions
  • Condensation stiffness study baseline — recorded timestep grid, fixed-four P2-finalized direct GPU contract, inclusive threshold semantics, and accepted (n_boxes,) environment inputs
• Epic B: Non-Isothermal Condensation Public API (CPU) (ADW plan E1) — public builder/factory access, validation, and documentation for latent-heat condensation on the CPU reference path.
• Epic C: GPU Kernel Correctness and Low-Level API Hardening (ADW plan E3) — persistent coagulation RNG state, bounded mixed-scale selector hardening, measured one-thread-per-box limits, documented direct kernel entry points, device-aware test policy, and the completed Epic B latent-heat example and integration baseline. Shipped artifacts:
  • Direct GPU kernels quick-start — explicit-transfer, two-call low-level condensation path with reused caller-owned fp64 sidecars; it does not invoke coagulation or configure RNG state
  • CPU latent-heat condensation example — runnable bookkeeping reference for future GPU parity
  • Measured coagulation decision record — accepted many-box baseline and large single-box caution band
• Epic D: GPU Condensation Physics Parity (ADW plan E4) is the shipped bounded low-level direct-condensation publication. It includes constant and Buck vapor-pressure refresh, ideal and kappa activity, static and composition-weighted surface tension, fixed-four P2 inventory finalization, gas coupling and conservation, latent-heat rate correction and signed energy diagnostics, reusable caller-owned fp64 sidecars, device-aware parity evidence, and the published direct-kernel support contract and example. It does not provide high-level runnable integration or general CPU-strategy parity.
  • Independent condensation walkthrough (docs/Examples/gpu_condensation_parity_walkthrough.py) — fixed-four-substep low-level direct-kernel physics, conservation, and energy evidence, with Warp CPU as the installed-Warp baseline; CUDA is optional additive evidence
  • Downstream condensation ownership record (condensation-parity-walkthrough.md) — deferred work only; it does not alter Epic D production capability or activate later epics
  • The walkthrough's caller-owned, write-only energy_transfer diagnostic is not a return value or temperature feedback (kg * J/kg = J). It preserves fixed-four-substep direct-kernel scope: no strategy/Runnable parity, adaptive stepping, graph capture/replay, broad autodiff, or performance claim.
  • Focused evidence commands: python docs/Examples/gpu_condensation_parity_walkthrough.py, pytest particula/gpu/tests/gpu_condensation_parity_walkthrough_test.py -q -Werror, and pytest particula/tests/condensation_parity_walkthrough_docs_test.py -q -Werror.
• Epic E: GPU Coagulation Physics Coverage (ADW plan E5) and all nine feature plans E5-F1 through E5-F9 shipped on 2026-07-20. The bounded direct-kernel release covers Brownian, charged hard-sphere, SP2016 sedimentation, and ST1956 turbulent-shear terms; approved additive masks; charge-conserving merges; deterministic and stochastic validation; explicit-transfer documentation and examples; and the ordered closeout gate. High-level Runnable integration remains deferred.

Active

• Epic F: GPU Process Completeness is the next and currently active epic. It adds CPU/GPU dilution, GPU wall loss, CPU/GPU nucleation, and fixed-slot activation and exhaustion handling needed for complete GPU-resident timesteps.

E5 roadmap inventory

ID	Title	Status text
E5	GPU Coagulation Physics Coverage	Shipped
E5-F1	Mechanism Configuration and Sampling Contract	Shipped
E5-F2	Charged Pair Physics and Charge-Conserving Merges	Shipped
E5-F3	Charged and Brownian-Plus-Charged GPU Execution	Shipped
E5-F4	SP2016 Sedimentation GPU Execution	Shipped
E5-F5	ST1956 Turbulent-Shear GPU Execution	Shipped
E5-F6	Single-Pass Additive Multi-Mechanism Coagulation	Shipped
E5-F7	Cross-Mechanism GPU Validation Matrix	Shipped
E5-F8	Independent CPU-Warp Condensation Walkthrough	Shipped
E5-F9	GPU Coagulation Support Documentation and Epic Closeout	Shipped

All E5 features are shipped. The public E5 cross-links are:

• E5-F7's GPU coagulation validation record.
• E5-F8's condensation parity walkthrough ownership record and runnable GPU condensation parity walkthrough.
• E5-F9's canonical GPU coagulation ownership contract, direct-kernel support guide, and direct GPU coagulation example.

E5 and every E5 feature are shipped. Epic F is active next; Epic G is on deck.

On Deck

• Epic G: Backend Selection and GPU-Resident Simulation follows Epic F. It will expose backend selection through user-facing APIs and keep complete simulation loops resident on the selected device between checkpoints.

Pending

Listed in execution order; each becomes active when the previous epic ships.

• Epic H: Graph Capture and Performance
• Epic I: Differentiability and Global Optimization — implementation companion: Warp autodiff limitations

Roadmap Artifacts

This folder can also hold supporting artifacts for planning and examples, such as design notes, example outputs, prototype workflows, and milestone-specific pages.

• Data-Oriented Design and GPU Roadmap

Reference anchors used by other documentation:

• Current container schema inventory
• Authoritative field ownership decisions
• Canonical shape conventions for container workflows
• Final downstream handoff map for sibling features
• CPU↔GPU restore boundary for ordered gas metadata
• Current CPU execution limits for multi-box-ready containers

Contribution Opportunities

• Add a new physics strategy with builder, factory, tests, and documentation.
• Convert lower-level utilities into feature-level examples that show complete workflows.
• Improve theory pages with citations, assumptions, and model limitations.
• Report missing documentation or unclear APIs in GitHub Issues or Discussions.

How to Propose Changes

For small fixes, open a pull request directly. For larger features, start with a GitHub Discussion so maintainers and users can align on scope, API shape, and testing expectations before implementation.