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.

Release and migration sequence

Maintainer decision, 2026-09-27: E8 and E8-F1 through E8-F8 are Shipped. The next milestones are:

1. Merge the E8 closeout and roadmap update.
2. Release 0.2.13, retaining both the legacy ParticleRepresentation / GasSpecies facades and the ParticleData / GasData / EnvironmentData container workflow.
3. Deliver 0.3.0 as the breaking container-first migration: remove the legacy facades, migrate dependent workflows, and update all affected documentation, examples, imports, and tests.
4. Continue Epic I, differentiability and initial-state optimization, after the migration milestone.

These are planned releases; this roadmap update does not publish a release. The closeout record records the maintainer's plan closure separately from unavailable CUDA measurement evidence.

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: Maintain the shipped GPU dilution, wall loss, nucleation, and fixed-capacity slot-management contracts from Epic F.
• GPU-resident user workflows: Maintain the shipped backend-selection, resident scheduling, communication, checkpoint/restart, diagnostics, and RNG contracts from Epic G.
• Graph capture and performance: Maintain shipped Epic H's bounded capture/replay and documentation tracks. Use the native-CUDA example, operator runbook, and closeout record. E8-F7/T7 owns profiling and machine-bounded recommendations; E8-F8 owns the example, runbook, limitations, and closeout. The closeout remains the sole P3 evidence authority; measured performance results remain unavailable and unshipped until reviewed. No CPU or Warp-CPU fallback is provided.
• 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.
• Epic F: GPU Process Completeness (ADW plan E6) and all nine feature plans E6-F1 through E6-F9 are shipped. The release supplies the bounded direct dilution, wall-loss, fixed-slot, exhaustion, and nucleation contracts plus explicit five-call sequence evidence. High-level GPU orchestration remains deferred to Epic G.
• Epic G: Backend Selection and GPU-Resident Simulation (ADW plan E7) and all nine feature plans E7-F1 through E7-F9 shipped on 2026-08-30. The release closes backend selection, explicit fallback policy, bounded process adapters, resident sessions and checkpoints, deterministic scheduling, prescribed communication and volume evolution, persistent RNG restart semantics, diagnostics, full-loop regressions, and documentation.

E6 roadmap inventory

ID	Title	Status text
E6	GPU Process Completeness	Shipped
E6-F1	CPU Dilution Strategy and Runnable Reference	Shipped
E6-F2	Direct GPU Dilution with CPU Parity	Shipped
E6-F3	Neutral Spherical and Rectangular GPU Wall Loss	Shipped
E6-F4	Charged GPU Wall Loss with Neutral Fallback	Shipped
E6-F5	CPU and GPU Fixed-Slot Activation and Diagnostics	Shipped
E6-F6	CPU and GPU Slot Exhaustion Policies	Shipped
E6-F7	CPU Nucleation and Particle-Source Process	Shipped
E6-F8	Direct GPU Nucleation Process	Shipped
E6-F9	Integrated Validation Documentation and Epic Closeout	Shipped

The private P2 sequence evidence, P3 source, and P3 regression document an explicit five-call sequence. Its condensation_step_gpu, coagulation_step_gpu, dilution_step_gpu, wall_loss_step_gpu, and nucleation_step_gpu order is illustrative, not a production coordinator.

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.

E7 roadmap inventory

ID	Title	Status text
E7	Backend Selection and GPU-Resident Simulation	Shipped
E7-F1	Backend-Selection and Execution-Context API	Shipped
E7-F2	Backend-Selected Condensation	Shipped
E7-F3	Backend-Selected Brownian Coagulation	Shipped
E7-F4	GPU-Resident Session State and Checkpoints	Shipped
E7-F5	Deterministic Full-Process Scheduling	Shipped
E7-F6	Fallback, Capability Errors, and API Stability	Shipped
E7-F7	Multi-Box Communication and Volume Evolution	Shipped
E7-F8	Persistent Per-Box RNG Streams and Restart Semantics	Shipped
E7-F9	Diagnostics, Full-Loop Regressions, Documentation, and Closeout	Shipped

E5, E6, E7, E8, and all of their feature plans are shipped.

E8 roadmap inventory

ID	Title	Status text
E8	Graph Capture and Performance	Shipped
E8-F1	Graph-Capture Capability and Lifecycle Contracts	Shipped
E8-F2	Capture-Ready Device Enqueue Paths	Shipped
E8-F3	Registry Preallocation, Identity Reuse, and Byte Accounting	Shipped
E8-F4	Resident Graph Capture and Guarded Replay Lifecycle	Shipped
E8-F5	Captured Full-Loop Parity and Lifecycle Validation	Shipped
E8-F6	Multi-Box Scaling Benchmarks and Memory-Budget Evidence	Shipped
E8-F7	CUDA Profiling and Machine-Bounded Performance Decisions	Shipped
E8-F8	Graph-Capture Example, Runbook, Limitations, and Closeout	Shipped

• Epic H: Graph Capture and Performance and its eight features were closed as Shipped by maintainer decision on 2026-09-27. Reviewed CUDA measurements remain unavailable; plan closure does not establish a measured performance claim. E8-F8 owns the example, runbook, limitations, and closeout, with no CPU or Warp-CPU fallback. The native-CUDA example, operator runbook, and P3 closeout record are the discoverable references; the closeout alone owns P3 status/evidence.

Pending

The 0.2.13 release and 0.3.0 migration take precedence over the next epic.

• 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.