refactor to StaticSMLM and Core modules

Author: kalidke

CLAUDE.md

@@ -0,0 +1,23 @@
+# SMLMSim.jl Development Guide
+
+## 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.

README.md

@@ -28,14 +28,16 @@ Pkg.add("SMLMSim")
 
 ## Basic Usage
 
-The high-level interface for simulating SMLM super-resolution coordinate data is the `simulate()` function (or the alias `sim()`).
+The high-level interface for simulating SMLM super-resolution coordinate data is the `simulate()` function with a `StaticSMLMParams` object.
 
 ```julia
 using SMLMSim
 
 # Basic simulation with default parameters
 camera = IdealCamera(1:128, 1:128, 0.1)  # 128×128 pixels, 100nm pixels
+params = StaticSMLMParams()  # Default parameters
 smld_true, smld_model, smld_noisy = simulate(
+    params,
     camera=camera
 )
 ```
@@ -57,16 +59,20 @@ For more control, you can customize the parameters:
 
 ```julia
 # More customized simulation
-smld_true, smld_model, smld_noisy = simulate(;
+params = StaticSMLMParams(
     ρ=1.0,                # emitters per μm²
     σ_psf=0.13,           # PSF width in μm (130nm)
     minphotons=50,        # minimum photons for detection
     ndatasets=10,         # number of independent datasets
     nframes=1000,         # frames per dataset
-    framerate=50.0,       # frames per second
+    framerate=50.0        # frames per second
+)
+
+smld_true, smld_model, smld_noisy = simulate(
+    params,
     pattern=Nmer2D(n=6, d=0.2),  # hexamer with 200nm diameter
     molecule=GenericFluor(; q=[0 50; 1e-2 0]),  # rates in 1/s
-    camera=IdealCamera(; ypixels=256, xpixels=128, pixelsize=0.1)  # pixelsize in μm
+    camera=IdealCamera(1:256, 1:128, 0.1)  # 128×256 pixels, 100nm pixels
 )
 ```
 
@@ -166,10 +172,15 @@ using CairoMakie
 # Create camera with physical pixel size
 camera = IdealCamera(1:128, 1:256, 0.1)  # 128×256 pixels, 100nm pixels
 
-# Simulation parameters in physical units
-smld_true, smld_model, smld_noisy = simulate(;
+# Create simulation parameters
+params = StaticSMLMParams(
     ρ=1.0,                # emitters per μm²
-    σ_psf=0.13,           # PSF width in μm
+    σ_psf=0.13            # PSF width in μm
+)
+
+# Run simulation
+smld_true, smld_model, smld_noisy = simulate(
+    params,
     pattern=Nmer2D(n=6, d=0.2),  # hexamer with 200nm diameter
     camera=camera
 )
@@ -212,13 +223,19 @@ using SMLMSim
 # Create camera with physical pixel size
 camera = IdealCamera(1:128, 1:256, 0.1)  # 128×256 pixels, 100nm pixels
 
-# Simulation parameters in physical units
-smld_true, smld_model, smld_noisy = simulate(;
+# Create 3D simulation parameters
+params = StaticSMLMParams(
     ρ=0.5,                # emitters per μm²
-    pattern=Nmer3D(n=8, d=0.3),  # 3D pattern
-    camera=camera,
+    ndims=3,              # 3D simulation
     zrange=[-2.0, 2.0]    # 4μm axial range
 )
+
+# Run simulation
+smld_true, smld_model, smld_noisy = simulate(
+    params,
+    pattern=Nmer3D(n=8, d=0.3),  # 3D pattern
+    camera=camera
+)
 ```
 
 ## Contributors

dev/basic_sim_test.jl

@@ -1,32 +1,39 @@
 using Revise
 using SMLMSim
-using SMLMData 
-
-
+using SMLMData
 
 # 2D Example
 camera = IdealCamera(1:512, 1:512, 0.1)
 pattern = SMLMSim.Nmer2D(n=6, d=0.2)
-smld_true, smld_model, smld_noisy = sim(
-    ρ=1.0,
+params = StaticSMLMParams(ρ=1.0)
+smld_true, smld_model, smld_noisy = simulate(
+    params,
     pattern=pattern,
     camera=camera
 )
 
 # 3D Example
 pattern3d = SMLMSim.Nmer3D(n=8, d=0.3)
-smld_true, smld_model, smld_noisy = sim(
+params3d = StaticSMLMParams(
     ρ=1.0,
-    pattern=pattern3d,
-    camera=camera,
+    ndims=3,
     zrange=[-2.0, 2.0]
 )
+smld_true, smld_model, smld_noisy = simulate(
+    params3d,
+    pattern=pattern3d,
+    camera=camera
+)
 
 # Complex Pattern Example
 line3d = SMLMSim.Line3D(λ=5.0, endpoints=[(-1.0, 0.0, -0.5), (1.0, 0.0, 0.5)])
-smld_true, smld_model, smld_noisy = sim(
+params_line = StaticSMLMParams(
     ρ=0.5,
-    pattern=line3d,
     σ_psf=0.15,
+    ndims=3
+)
+smld_true, smld_model, smld_noisy = simulate(
+    params_line,
+    pattern=line3d,
     camera=camera
 )

dev/sim2D.jl

@@ -6,16 +6,24 @@ using GLMakie
 # Create camera with physical pixel size
 camera = IdealCamera(1:128, 1:256, 0.1)  # 128x256 pixels, 100nm pixels
 
-# Simulation parameters in physical units
-smld_true, smld_model, smld_noisy = SMLMSim.sim(;
+# Create StaticSMLMParams with simulation parameters
+params = StaticSMLMParams(
     ρ=1.0,                # emitters per μm²
     σ_psf=0.13,          # PSF width in μm
     minphotons=50,       # minimum photons for detection
     ndatasets=10,        # number of independent datasets
     nframes=1000,        # frames per dataset
-    framerate=50.0,      # frames per second
-    pattern=SMLMSim.Nmer2D(),
-    molecule=SMLMSim.GenericFluor(; q=[0 50; 1e-2 0]),  # rates in 1/s
+    framerate=50.0      # frames per second
+)
+
+# Run simulation with type-based interface
+pattern = SMLMSim.Nmer2D()
+molecule = SMLMSim.GenericFluor(; q=[0 50; 1e-2 0])  # rates in 1/s
+
+smld_true, smld_model, smld_noisy = simulate(
+    params,
+    pattern=pattern,
+    molecule=molecule,
     camera=camera
 )
 

dev/sim3d.jl

@@ -6,18 +6,27 @@ using GLMakie
 # Create camera with physical pixel size
 camera = IdealCamera(1:128, 1:256, 0.1)  # 128x256 pixels, 100nm pixels
 
-# Simulation parameters in physical units
-smld_true, smld_model, smld_noisy = SMLMSim.sim(;
-    ρ=100.0,                # emitters per μm²
-    σ_psf=0.13,          # PSF width in μm
-    minphotons=50,       # minimum photons for detection
-    ndatasets=10,        # number of independent datasets
-    nframes=1000,        # frames per dataset
-    framerate=50.0,      # frames per second
-    pattern=SMLMSim.Nmer3D(),  # Using 3D pattern
-    molecule=SMLMSim.GenericFluor(; q=[0 50; 1e-2 0]),
-    camera=camera,
-    zrange=[-1.0, 1.0]   # Set z range for 3D patterns
+# Create StaticSMLMParams with simulation parameters
+params = StaticSMLMParams(
+    ρ=100.0,              # emitters per μm²
+    σ_psf=0.13,           # PSF width in μm
+    minphotons=50,        # minimum photons for detection
+    ndatasets=10,         # number of independent datasets
+    nframes=1000,         # frames per dataset
+    framerate=50.0,       # frames per second
+    ndims=3,              # 3D simulation
+    zrange=[-1.0, 1.0]    # Set z range for 3D patterns
+)
+
+# Run simulation with type-based interface
+pattern = SMLMSim.Nmer3D()  # Using 3D pattern
+molecule = SMLMSim.GenericFluor(; q=[0 50; 1e-2 0])
+
+smld_true, smld_model, smld_noisy = simulate(
+    params,
+    pattern=pattern,
+    molecule=molecule,
+    camera=camera
 )
 
 # Extract coordinates from emitters

docs/src/api.md

@@ -58,8 +58,8 @@ GenericFluor
 
 ```@docs
 CTMC
-getstate
-getnext
+get_state
+get_next
 intensitytrace
 kineticmodel
 ```

src/SMLMSim.jl

@@ -7,12 +7,18 @@ using LinearAlgebra
 # Re-export critical types from SMLMData to make them available to users
 export AbstractCamera, IdealCamera, AbstractEmitter, Emitter2D, Emitter3D, Emitter2DFit, Emitter3DFit, BasicSMLD
 
-include("molecules.jl")
-include("patterns.jl")
-include("sim.jl")
+# Core module (includes molecules.jl and patterns.jl internally)
+include("core/Core.jl")
+
 include("interface.jl")
 
-# Submodules
+# Import specific functions from Core
+using .Core: CTMC, get_state, get_next, intensity_trace, kinetic_model
+using .Core: Molecule, GenericFluor, Pattern, Pattern2D, Pattern3D
+using .Core: Nmer2D, Nmer3D, Line2D, Line3D, uniform2D, uniform3D, rotate!
+
+# Include submodules after the Core imports are available
+include("static/StaticSMLM.jl")
 include("diffusion/InteractionDiffusion.jl")
 
 # Import specific functions from InteractionDiffusion
@@ -21,28 +27,24 @@ using .InteractionDiffusion: DiffusingMolecule, DiffusingMoleculeSystem,
                             show_frame, visualize_sequence, visualize_simulation,
                             gen_image, gen_image_sequence
 
-# Add this line to import the simulate method
-using .InteractionDiffusion: simulate
+# Import from StaticSMLM
+using .StaticSMLM: StaticSMLMParams, apply_noise
 
-# Export molecule types
-export
-    # Abstract molecule types
-    Molecule,
-    
-    # Concrete molecule types
-    GenericFluor
+# Add this line to import the simulate methods
+using .InteractionDiffusion: simulate
+using .StaticSMLM: simulate
 
 # Export simulation functions
 export
     # Kinetic simulation
-    intensitytrace,
-    kineticmodel,
+    intensity_trace, # Renamed from intensitytrace to match function name
+    kinetic_model,   # Renamed from kineticmodel to match function name
     noise,
 
     # CTMC type and functions
     CTMC,
-    getstate,
-    getnext
+    get_state,
+    get_next
 
 # Core types and functions for diffusion simulation
 export
@@ -57,8 +59,8 @@ export
     # Analysis functions
     get_dimers,
     gen_dimer_images,
-    gen_image,         # Add this
-    gen_image_sequence # Add this
+    gen_image,         
+    gen_image_sequence 
 
 # Pattern simulation types and functions
 export
@@ -81,6 +83,18 @@ export
     # Full simulation pipeline
     sim
 
+# Export molecule types
+export
+    # Abstract molecule types
+    Molecule,
+    
+    # Concrete molecule types
+    GenericFluor,
+    
+    # Static SMLM types
+    StaticSMLMParams,
+    apply_noise
+
 # Visualization
 export
     show_frame,