docs: Add project todo list and roadmap

- Milestone-based task organization - OpenMM API mapping table - Target directory structure - Design decisions log
2026-01-10 23:57:09 +09:00
parent 8d902724f9
commit cb7f3d2176
1 changed files with 361 additions and 0 deletions
--- a/todo.md
+++ b/todo.md
@@ -0,0 +1,361 @@
+# Simul - Unified Simulation Framework
+
+## Overview
+
+A modular Rust workspace for simulation of physical systems:
+- **simul-core** - Core traits and abstractions
+- **simul-euclidean** - Continuous space (MD, Brownian)
+- **simul-lattice** - Discrete space (Ising, MC)
+- **simul-sampling** - Advanced sampling (future)
+- **simul** - Facade crate (re-exports all)
+
+**Key Features:**
+- Variable dimensions (1D, 2D, 3D, ...) via const generics
+- Continuous & discrete state spaces
+- Deterministic & stochastic dynamics
+- Builder + Iterator API
+
+---
+
+## 🏗️ Milestone 0: Workspace Setup
+
+> Restructure from single crate to workspace
+
+- [ ] Create workspace `simul/`
+- [ ] Move current code to `simul-legacy/` (temporary)
+- [ ] Create `simul-core/` skeleton
+- [ ] Create `simul-euclidean/` skeleton
+- [ ] Create `simul-lattice/` skeleton
+- [ ] Create `simul/` facade
+- [ ] Update root `Cargo.toml` as workspace manifest
+
+---
+
+## 🎯 Milestone 1: simul-core
+
+> Core traits and shared abstractions
+
+### Phase 1.1: StateSpace Trait
+
+- [ ] **StateSpace trait** (`simul-core/src/space/mod.rs`)
+  - `const DIM: usize`
+  - `type Point`
+  - `type Momentum`
+  - `fn is_continuous() -> bool`
+
+### Phase 1.2: SystemState
+
+- [ ] **SystemState<S: StateSpace>** (`simul-core/src/state.rs`)
+  - `positions: Vec<S::Point>`
+  - `momenta: Vec<S::Momentum>`
+  - `masses: Vec<f64>`
+  - `time: f64`, `step: usize`
+  - `auxiliary: AuxiliaryState`
+
+### Phase 1.3: Dynamics Trait
+
+- [ ] **Dynamics trait** (`simul-core/src/dynamics.rs`)
+  - `fn step<R: Rng>(&self, state: &mut SystemState<S>, rng: &mut R) -> f64`
+  - `fn is_deterministic(&self) -> bool`
+  - `fn time_type(&self) -> TimeType`
+
+- [ ] **TimeType enum**
+  - `Continuous` / `Discrete`
+
+### Phase 1.4: Interaction Trait
+
+- [ ] **Interaction trait** (`simul-core/src/interaction.rs`)
+  - `type Output`
+  - `fn compute(&self, state: &SystemState<S>) -> Self::Output`
+
+- [ ] **Output types**
+  - `ForceOutput<D>` (forces + potential)
+  - `EnergyOutput` (for MC)
+  - `RateOutput` (for CTMC)
+
+### Phase 1.5: Shared Types
+
+- [ ] Units (`simul-core/src/units.rs`) - move from current
+- [ ] Errors (`simul-core/src/error.rs`) - move from current
+- [ ] Prelude (`simul-core/src/prelude.rs`)
+
+---
+
+## 🎯 Milestone 2: simul-euclidean
+
+> Continuous Euclidean space simulations
+
+### Phase 2.1: Space Implementation
+
+- [ ] **Euclidean<D>** (`simul-euclidean/src/space.rs`)
+  - `Point = SVector<f64, D>`
+  - `Momentum = SVector<f64, D>`
+  - Type aliases: `Space1D`, `Space2D`, `Space3D`
+
+### Phase 2.2: Dynamics
+
+- [ ] **VerletDynamics<D>** - velocity Verlet (deterministic)
+- [ ] **LangevinDynamics<D>** - Langevin equation (stochastic)
+- [ ] **BrownianDynamics<D>** - overdamped (no inertia)
+
+### Phase 2.3: Interactions
+
+- [ ] **NonbondedInteraction<D>** - L-J + Coulomb
+- [ ] **HarmonicBondInteraction<D>** - bonds
+- [ ] **HarmonicAngleInteraction<D>** - angles
+- [ ] **ExternalFieldInteraction<D>** - external potentials
+
+### Phase 2.4: Simulation
+
+- [ ] **Simulation<S>** with builder
+- [ ] **SimulationIterator**
+- [ ] CPU parallel backend (feature: `cpu`)
+
+---
+
+## 🎯 Milestone 3: simul-lattice
+
+> Discrete lattice space simulations
+
+### Phase 3.1: Space Implementation
+
+- [ ] **Lattice<D>** (`simul-lattice/src/space.rs`)
+  - `Point = SVector<i64, D>`
+  - `Momentum = ()`
+  - Size, periodic boundary
+
+- [ ] **SpinLattice<D>** (for Ising-like models)
+  - Spin states (+1/-1)
+
+### Phase 3.2: Dynamics
+
+- [ ] **MetropolisDynamics<D>** - Metropolis MC
+- [ ] **GlauberDynamics<D>** - heat bath
+- [ ] **GillespieDynamics<D>** - continuous-time MC
+- [ ] **KawasakiDynamics<D>** - conserved dynamics
+
+### Phase 3.3: Interactions
+
+- [ ] **IsingInteraction<D>** - nearest-neighbor coupling
+- [ ] **PottsInteraction<D>** - q-state Potts
+- [ ] **LatticeGasInteraction<D>** - lattice gas
+
+---
+
+## 🎯 Milestone 4: Examples
+
+### From simul-euclidean
+
+- [ ] **hello_argon.rs** - 3D L-J MD (migrate from current)
+- [ ] **brownian_1d.rs** - 1D Brownian motion
+- [ ] **brownian_2d.rs** - 2D Brownian motion
+- [ ] **langevin_particle.rs** - Langevin dynamics
+
+### From simul-lattice
+
+- [ ] **ising_2d.rs** - 2D Ising model (Metropolis)
+- [ ] **ising_2d_glauber.rs** - 2D Ising (Glauber)
+- [ ] **random_walk_2d.rs** - 2D lattice random walk
+- [ ] **lattice_gas_2d.rs** - 2D lattice gas
+
+---
+
+## 🎯 Milestone 5: simul-sampling (Future)
+
+> Advanced sampling methods
+
+- [ ] **ReplicaExchange** - parallel tempering
+- [ ] **UmbrellaSampling** - biased sampling
+- [ ] **WangLandau** - flat histogram
+- [ ] **Metadynamics** - adaptive bias
+
+---
+
+## 🎯 Milestone 6: Performance (Future)
+
+- [ ] SIMD optimization (packed operations)
+- [ ] GPU support (CUDA feature)
+- [ ] GPU support (OpenCL feature)
+- [ ] Neighbor lists (cell list, Verlet list)
+
+---
+
+## 📊 Progress Tracking
+
+### Completed ✅
+
+- [x] Initial project setup (rust-openmm)
+- [x] Design document v1
+- [x] Basic units module
+- [x] Error handling with thiserror
+- [x] Vector3-based System
+- [x] NonbondedForce (L-J)
+- [x] VerletIntegrator
+- [x] Simulation + Builder + Iterator
+- [x] CPU parallel backend
+- [x] HelloArgon example (working)
+- [x] Design document v2 (generalized, multi-crate)
+- [x] Todo list updated for workspace structure
+
+### In Progress 🔄
+
+- [ ] Milestone 0: Workspace setup
+
+### Pending ⏳
+
+- See milestones above
+
+---
+
+## 📁 Target Directory Structure
+
+```
+simul/                             # Workspace root
+├── Cargo.toml                     # Workspace manifest
+├── DESIGN.md                      
+├── README.md
+│
+├── simul-core/                    # 핵심 trait + 공용 타입
+│   ├── Cargo.toml                 # nalgebra, thiserror, rand
+│   └── src/
+│       ├── lib.rs
+│       ├── space/
+│       │   ├── mod.rs             # StateSpace trait
+│       │   └── traits.rs          # Point, Momentum bounds
+│       ├── dynamics.rs            # Dynamics trait ← Integrator
+│       ├── interaction.rs         # Interaction trait ← Force
+│       ├── state.rs               # SystemState<S> ← System+State
+│       ├── units.rs               # Dalton, Nanometer, Picosecond, KJPerMol, Kelvin
+│       ├── error.rs               # SimulationError
+│       └── prelude.rs
+│
+├── simul-euclidean/               # 연속 공간 시뮬레이션
+│   ├── Cargo.toml                 # simul-core, rayon
+│   └── src/
+│       ├── lib.rs
+│       ├── space.rs               # Euclidean<D>: Point=SVector<f64,D>
+│       ├── dynamics/
+│       │   ├── mod.rs
+│       │   ├── verlet.rs          # ← VerletIntegrator (velocity Verlet)
+│       │   ├── langevin.rs        # ← LangevinIntegrator (stochastic)
+│       │   └── brownian.rs        # ← BrownianIntegrator (overdamped)
+│       ├── interaction/
+│       │   ├── mod.rs
+│       │   ├── nonbonded.rs       # ← NonbondedForce (L-J, Coulomb)
+│       │   ├── harmonic_bond.rs   # ← HarmonicBondForce
+│       │   ├── harmonic_angle.rs  # ← HarmonicAngleForce
+│       │   └── external.rs        # ← CustomExternalForce
+│       ├── simulation/
+│       │   ├── mod.rs             # Simulation<S> ← Context
+│       │   ├── builder.rs         # SimulationBuilder
+│       │   └── iterator.rs        # SimulationIterator
+│       ├── platform/
+│       │   ├── mod.rs             # ComputeBackend trait ← Platform
+│       │   └── cpu.rs             # CpuBackend ← ReferencePlatform
+│       └── prelude.rs
+│
+├── simul-lattice/                 # 이산 공간 시뮬레이션 (non-OpenMM)
+│   ├── Cargo.toml                 # simul-core
+│   └── src/
+│       ├── lib.rs
+│       ├── space.rs               # Lattice<D>, SpinLattice<D>
+│       ├── dynamics/
+│       │   ├── mod.rs
+│       │   ├── metropolis.rs      # Metropolis-Hastings MC
+│       │   ├── glauber.rs         # Glauber (heat-bath) dynamics
+│       │   ├── kawasaki.rs        # Kawasaki (conserved) dynamics
+│       │   └── gillespie.rs       # Gillespie SSA (CTMC)
+│       ├── interaction/
+│       │   ├── mod.rs
+│       │   ├── ising.rs           # Ising model H = -J Σ s_i s_j
+│       │   ├── potts.rs           # q-state Potts model
+│       │   └── lattice_gas.rs     # Lattice gas model
+│       └── prelude.rs
+│
+├── simul-sampling/                # 고급 샘플링 (future)
+│   └── src/
+│       ├── replica_exchange.rs    # Parallel tempering
+│       ├── umbrella.rs            # Umbrella sampling
+│       ├── wang_landau.rs         # Wang-Landau flat histogram
+│       └── metadynamics.rs        # Adaptive bias
+│
+├── simul/                         # Facade (re-export all)
+│   ├── Cargo.toml
+│   └── src/
+│       ├── lib.rs
+│       └── prelude.rs             # use simul::prelude::*;
+│
+└── examples/
+    ├── hello_argon.rs             # 3D L-J gas, 36 atoms
+    ├── brownian_1d.rs             # 1D Brownian in harmonic trap
+    ├── brownian_2d.rs             # 2D Brownian diffusion
+    ├── langevin_particle.rs       # Langevin dynamics demo
+    ├── ising_2d.rs                # 2D Ising, phase transition
+    ├── ising_2d_glauber.rs        # 2D Ising with Glauber
+    └── random_walk_2d.rs          # 2D lattice random walk
+```
+
+---
+
+## 📝 Design Decisions Log
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+| 2026-01-10 | Workspace with multi-crate | Modularity, selective dependencies |
+| 2026-01-10 | `simul` as project name | Short, general, memorable |
+| 2026-01-10 | `simul-core` for traits | Shared by all simulation types |
+| 2026-01-10 | `simul-euclidean` for continuous | MD, Brownian, Langevin |
+| 2026-01-10 | `simul-lattice` for discrete | Ising, MC, random walk |
+| 2026-01-10 | Const generic dimension | Zero-cost, compile-time optimization |
+| 2026-01-10 | StateSpace trait | Unified continuous/discrete spaces |
+| 2026-01-10 | Dynamics replaces Integrator | Covers deterministic + stochastic |
+| 2026-01-10 | Enum-based dispatch | Type-safe runtime polymorphism |
+| 2026-01-10 | Builder + Iterator API | Ergonomic, functional style |
+| 2026-01-10 | thiserror for errors | Clear, typed error handling |
+| 2026-01-10 | `cpu` feature (parallel) | rayon-based parallelization |
+
+---
+
+## 🔄 OpenMM API Mapping
+
+| OpenMM (C++) | simul (Rust) | Location |
+|--------------|--------------|----------|
+| `System` | `SystemState<S>` | `simul-core/state.rs` |
+| `Context` | `Simulation<S>` | `simul-euclidean/simulation/` |
+| `State` | `StateSnapshot` | `simul-core/state.rs` |
+| `Platform` | `ComputeBackend` trait | `simul-euclidean/platform/` |
+| `Integrator` | `Dynamics<S>` trait | `simul-core/dynamics.rs` |
+| `Force` | `Interaction<S>` trait | `simul-core/interaction.rs` |
+| — | — | — |
+| `VerletIntegrator` | `VerletDynamics<D>` | `simul-euclidean/dynamics/verlet.rs` |
+| `LangevinIntegrator` | `LangevinDynamics<D>` | `simul-euclidean/dynamics/langevin.rs` |
+| `BrownianIntegrator` | `BrownianDynamics<D>` | `simul-euclidean/dynamics/brownian.rs` |
+| — | — | — |
+| `NonbondedForce` | `NonbondedInteraction<D>` | `simul-euclidean/interaction/nonbonded.rs` |
+| `HarmonicBondForce` | `HarmonicBondInteraction<D>` | `simul-euclidean/interaction/harmonic_bond.rs` |
+| `HarmonicAngleForce` | `HarmonicAngleInteraction<D>` | `simul-euclidean/interaction/harmonic_angle.rs` |
+| `CustomExternalForce` | `ExternalFieldInteraction<D>` | `simul-euclidean/interaction/external.rs` |
+| — | — | — |
+| `ReferencePlatform` | `CpuBackend` | `simul-euclidean/platform/cpu.rs` |
+| `CudaPlatform` | `CudaBackend` (future) | — |
+| `OpenCLPlatform` | `OpenClBackend` (future) | — |
+
+**Non-OpenMM extensions (simul-lattice):**
+
+| Model | Struct | Location |
+|-------|--------|----------|
+| Ising model | `IsingInteraction<D>` | `simul-lattice/interaction/ising.rs` |
+| Potts model | `PottsInteraction<D>` | `simul-lattice/interaction/potts.rs` |
+| Lattice gas | `LatticeGasInteraction<D>` | `simul-lattice/interaction/lattice_gas.rs` |
+| Metropolis MC | `MetropolisDynamics<D>` | `simul-lattice/dynamics/metropolis.rs` |
+| Glauber dynamics | `GlauberDynamics<D>` | `simul-lattice/dynamics/glauber.rs` |
+| Gillespie SSA | `GillespieDynamics<D>` | `simul-lattice/dynamics/gillespie.rs` |
+
+---
+
+## 📚 References
+
+- [OpenMM C++ API](http://docs.openmm.org/latest/api-c++/)
+- [Frenkel & Smit - Understanding Molecular Simulation](https://www.sciencedirect.com/book/9780122673511/)
+- [Allen & Tildesley - Computer Simulation of Liquids](https://global.oup.com/academic/product/computer-simulation-of-liquids-9780198803195)
+- [Newman & Barkema - Monte Carlo Methods in Statistical Physics](https://global.oup.com/academic/product/monte-carlo-methods-in-statistical-physics-9780198517979)