Merge pull request #31 from JuliaSMLM/feature/tuple-pattern

Add tuple-pattern return format for simulate and gen_images

Author: kalidke

CLAUDE.md

@@ -1,23 +1,93 @@
-# SMLMSim.jl Development Guide
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ## Build, Test & Run Commands
-- Install dependencies: `julia --project -e "using Pkg; Pkg.instantiate()"`
-- Run all tests: `julia --project -e "using Pkg; Pkg.test()"`
-- Run specific test: `julia --project -e "using Pkg; Pkg.test(\"SMLMSim\", test_args=[\"Patterns\"])"`
-- Build docs: `julia --project=docs/ docs/make.jl`
-- Run benchmark: `julia --project=dev/ dev/benchmark.jl`
-
-## Code Style Guidelines
-- Use physical units consistently (μm for space, seconds for time)
-- Follow Julia naming conventions: lowercase for functions, CamelCase for types
-- Organize imports: standard library first, then external packages
-- Place exports at module level, grouped by functionality
-- Type parameters should be explicit for functions with multiple dispatch
-- Error handling: use descriptive errors with parameter names and constraints
-- Documentation: include docstrings with examples and physical units
-- Re-export SMLMData types rather than redefining them
-- Follow existing patterns for defining new molecule or pattern types
-- Tests should use the `@test` macro with appropriate tolerances for floating-point comparisons
-
-## Module Structure
-Functions should be organized in appropriate submodules: core, static, or diffusion.
+
+```bash
+# Install dependencies
+julia --project -e "using Pkg; Pkg.instantiate()"
+
+# Run all tests
+julia --project -e "using Pkg; Pkg.test()"
+
+# Run specific test file (matches testset names like "Patterns", "Static", "Core")
+julia --project -e "using Pkg; Pkg.test(\"SMLMSim\", test_args=[\"Patterns\"])"
+
+# Build documentation
+julia --project=docs/ docs/make.jl
+
+# Run dev scripts
+julia --project=dev/ dev/benchmark.jl
+```
+
+## Architecture Overview
+
+SMLMSim simulates Single Molecule Localization Microscopy (SMLM) data. The package has four main modules that build on SMLMData.jl types:
+
+```
+SMLMSim (main module - re-exports from submodules)
+├── Core           - Shared types and photophysics
+├── StaticSMLM     - Fixed emitter simulation with blinking
+├── InteractionDiffusion - Diffusing/interacting molecules (SPT)
+└── CameraImages   - Generate camera images from emitters
+```
+
+### Simulation Pipeline (Static)
+
+```
+Pattern (geometry)
+  → uniform2D/3D() → binding site coordinates
+  → apply_labeling() → fluorophore positions (via AbstractLabeling)
+  → create emitters → smld_true (BasicSMLD)
+  → kinetic_model() → smld_model (with blinking, uses Molecule)
+  → apply_noise() → smld_noisy (with localization uncertainty)
+```
+
+Key separation of concerns:
+- **Pattern**: Spatial geometry of binding sites (Nmer2D, Line3D, etc.)
+- **Labeling**: How many fluorophores per site (FixedLabeling, PoissonLabeling, BinomialLabeling)
+- **Molecule**: Photophysics/blinking kinetics (GenericFluor with CTMC rate matrix)
+
+### Type Hierarchy
+
+```julia
+# Patterns (geometry)
+Pattern → Pattern2D → Nmer2D, Line2D
+        → Pattern3D → Nmer3D, Line3D
+
+# Labeling (fluorophore attachment statistics)
+AbstractLabeling → FixedLabeling, PoissonLabeling, BinomialLabeling
+
+# Molecules (photophysics)
+Molecule → GenericFluor
+
+# Simulation params
+SMLMSimParams → StaticSMLMConfig, DiffusionSMLMConfig
+```
+
+### Key Files by Function
+
+| Purpose | Files |
+|---------|-------|
+| Pattern geometry | `src/core/patterns.jl` |
+| Labeling statistics | `src/core/labeling.jl` |
+| Photophysics/blinking | `src/core/molecules.jl`, `src/core/photophysics.jl` |
+| CTMC (state transitions) | `src/core/ctmc.jl` |
+| Static simulation | `src/static/simulation.jl`, `src/static/parameters.jl` |
+| Diffusion simulation | `src/diffusion/smoluchowski.jl`, `src/diffusion/types.jl` |
+| Image generation | `src/camera_images/gen_images.jl`, `src/camera_images/noise.jl` |
+
+### Dispatch Pattern
+
+The `simulate()` function dispatches on parameter type:
+- `simulate(params::StaticSMLMConfig; ...)` → static simulation (returns 3-tuple)
+- `simulate(params::DiffusionSMLMConfig; ...)` → diffusion simulation (returns BasicSMLD)
+
+## Code Style
+
+- Physical units: μm for space, seconds for time
+- Re-export SMLMData types rather than redefining
+- Follow existing patterns when adding new Pattern, Labeling, or Molecule types
+- Type parameters explicit for multiple dispatch functions
+- Tests use `@test` with tolerances for floating-point comparisons

Project.toml

@@ -1,6 +1,6 @@
 name = "SMLMSim"
 uuid = "5a0a87e4-02d4-41f5-bf26-b8c94c784a04"
-version = "0.4.0"
+version = "0.6.0"
 authors = ["klidke@unm.edu"]
 
 [deps]
@@ -14,7 +14,7 @@ Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 [compat]
 Distributions = "0.25"
 MicroscopePSFs = "0.5"
-SMLMData = "0.4, 0.5"
+SMLMData = "0.7"
 julia = "1.6"
 
 [extras]

README.md

@@ -35,19 +35,20 @@ using SMLMSim
 
 # Define a camera and simulation parameters
 camera = IdealCamera(128, 128, 0.1)  # 128×128 pixels, 100nm pixels
-params = StaticSMLMParams(density=1.0, σ_psf=0.13) # Density 1/μm², PSF 130nm
+params = StaticSMLMConfig(density=1.0, σ_psf=0.13) # Density 1/μm², PSF 130nm
 
 # Run simulation for an 8-molecule ring pattern
-smld_true, smld_model, smld_noisy = simulate(
+smld_noisy, info = simulate(
     params; # Use semicolon to separate positional and keyword arguments
     pattern=Nmer2D(n=8, d=0.1), # 100nm diameter ring
     camera=camera
 )
 
 # smld_noisy contains realistic SMLM coordinates
+# info.smld_true and info.smld_model contain intermediate results
 println("Generated $(length(smld_noisy.emitters)) localizations.")
 ```
-*Output:* `smld_true` (ground truth), `smld_model` (kinetics), `smld_noisy` (kinetics + noise).
+*Output:* `smld_noisy` (kinetics + noise), `info` (SimInfo with `smld_true`, `smld_model`, timing).
 
 ### Diffusion & Interaction Simulation
 
@@ -57,7 +58,7 @@ Simulate molecules diffusing and interacting (e.g., dimerization).
 using SMLMSim
 
 # Set diffusion simulation parameters
-params = DiffusionSMLMParams(
+params = DiffusionSMLMConfig(
     density = 0.5,           # molecules per μm²
     box_size = 10.0,         # μm
     diff_monomer = 0.1,      # μm²/s
@@ -69,7 +70,7 @@ params = DiffusionSMLMParams(
 )
 
 # Run diffusion simulation
-smld = simulate(params) # Returns a BasicSMLD object with all emitters
+smld, info = simulate(params) # Returns (BasicSMLD, SimInfo)
 
 println("Simulated diffusion for $(params.t_max) seconds.")
 # 'smld' can be used for analysis or image generation
@@ -108,15 +109,15 @@ Create camera images from simulation results.
 using MicroscopePSFs # Needed for PSF types
 
 # Generate images from diffusion simulation output
-# Note: Frame timing is controlled by DiffusionSMLMParams (camera_framerate, camera_exposure)
+# Note: Frame timing is controlled by DiffusionSMLMConfig (camera_framerate, camera_exposure)
 # Multiple simulation timesteps are automatically integrated during simulate()
 psf = GaussianPSF(0.15) # 150nm PSF width
-images = gen_images(smld, psf;
+images, img_info = gen_images(smld, psf;
     support=1.0,        # PSF support radius in μm (faster than default Inf)
     poisson_noise=true  # Add shot noise
 )
 
-println("Generated $(size(images,3)) camera images.")
+println("Generated $(img_info.frames_generated) camera images.")
 ```
 
 ### sCMOS Camera with Realistic Noise
@@ -131,8 +132,8 @@ using MicroscopePSFs
 camera_scmos = SCMOSCamera(128, 128, 0.1, 1.6)
 
 # Run static simulation with sCMOS camera
-params = StaticSMLMParams(density=1.0, σ_psf=0.13)
-smld_true, smld_model, smld_noisy = simulate(
+params = StaticSMLMConfig(density=1.0, σ_psf=0.13)
+smld_noisy, info = simulate(
     params,
     pattern=Nmer2D(n=8, d=0.1),
     camera=camera_scmos
@@ -141,11 +142,11 @@ smld_true, smld_model, smld_noisy = simulate(
 # Generate images with full sCMOS noise model
 # (quantum efficiency, Poisson, read noise, gain, offset)
 psf = GaussianPSF(0.15)
-images_scmos = gen_images(smld_noisy, psf, bg=10.0, camera_noise=true)
+images_scmos, img_info = gen_images(smld_noisy, psf, bg=10.0, camera_noise=true)
 
 # For diffusion simulations
-diff_params = DiffusionSMLMParams(density=0.5, box_size=10.0)
-smld_diff = simulate(diff_params; camera=camera_scmos, override_count=10)
+diff_params = DiffusionSMLMConfig(density=0.5, box_size=10.0)
+smld_diff, diff_info = simulate(diff_params; camera=camera_scmos, override_count=10)
 ```
 
 The sCMOS noise model applies:
@@ -164,8 +165,8 @@ using MicroscopePSFs
 
 # --- Simulation Setup ---
 camera = IdealCamera(128, 128, 0.1) # 128×128 pixels, 100nm pixels
-params = StaticSMLMParams(density=1.0, σ_psf=0.13)
-smld_true, smld_model, smld_noisy = simulate(
+params = StaticSMLMConfig(density=1.0, σ_psf=0.13)
+smld_noisy, info = simulate(
     params,
     pattern=Nmer2D(n=6, d=0.2), # Hexamer
     camera=camera
@@ -202,24 +203,24 @@ using Statistics
 camera_scmos = SCMOSCamera(64, 64, 0.1, 1.6)  # 64×64 pixels, 100nm/px, 1.6 e⁻ read noise
 
 # Run diffusion simulation
-params = DiffusionSMLMParams(
+params = DiffusionSMLMConfig(
     density = 1.0,           # 1 molecule/μm²
     box_size = 6.4,          # 6.4×6.4 μm field
     diff_monomer = 0.1,      # 0.1 μm²/s diffusion
     t_max = 0.5,             # 0.5 second total
     camera_framerate = 100.0 # 100 fps
 )
-smld = simulate(params; camera=camera_scmos, photons=200.0)
+smld, info = simulate(params; camera=camera_scmos, photons=200.0)
 
 # Generate images with full sCMOS noise model
 # (quantum efficiency, Poisson, read noise, gain, offset)
 psf = GaussianPSF(0.13)  # 130nm PSF
-images_scmos = gen_images(smld, psf, bg=10.0, camera_noise=true)
+images_scmos, _ = gen_images(smld, psf, bg=10.0, camera_noise=true)
 
 # For comparison: same data with ideal camera (Poisson noise only)
 camera_ideal = IdealCamera(64, 64, 0.1)
 smld_ideal = BasicSMLD(smld.emitters, camera_ideal, smld.n_frames, smld.n_datasets)
-images_ideal = gen_images(smld_ideal, psf, bg=10.0, poisson_noise=true)
+images_ideal, _ = gen_images(smld_ideal, psf, bg=10.0, poisson_noise=true)
 
 # Compare statistics
 println("sCMOS: mean=$(round(mean(images_scmos), digits=1)) ADU, std=$(round(std(images_scmos), digits=1))")