refactor interfaces and code - this is a major breaking change even within this branch. Still needs testing.

Author: kalidke

src/SMLMSim.jl

@@ -15,6 +15,25 @@ include("diffusion/InteractionDiffusion.jl")
 
 using .InteractionDiffusion
 
+# Export molecule types
+export
+    # Abstract molecule types
+    Molecule,
+    
+    # Concrete molecule types
+    GenericFluor
+
+# Export simulation functions
+export
+    # Kinetic simulation
+    intensitytrace,
+    kineticmodel,
+    noise,
+    
+    # CTMC type and functions
+    CTMC,
+    getstate,
+    getnext
 
 # Core types and functions for diffusion simulation
 export
@@ -59,5 +78,4 @@ export
     visualize_simulation
 
 
-end
-
+end

src/diffusion/InteractionDiffusion.jl

@@ -1,6 +1,41 @@
 """
-This module provides simulation tools for diffusion
-    and interaction between particles.
+    InteractionDiffusion
+
+This module provides simulation tools for diffusion and interaction between particles.
+
+# Overview
+Simulates diffusion and interaction dynamics between particles in 2D/3D space.
+Includes functionality for generating microscope images, analyzing dimers, and
+visualizing particle dynamics.
+
+# Components
+- Core simulation types (DiffusingMolecule, DiffusingMoleculeSystem)
+- Smoluchowski dynamics simulation
+- Visualization tools
+- Microscope image generation
+- Dimer analysis and extraction
+
+# Examples
+```julia
+# Set up simulation parameters
+params = SmoluchowskiParams(
+    density = 0.5,        # molecules per μm²
+    box_size = 10.0,      # μm
+    diff_monomer = 0.1,   # μm²/s
+    diff_dimer = 0.05,    # μm²/s
+    k_off = 0.2,          # s⁻¹
+    r_react = 0.01,       # μm
+    d_dimer = 0.05,       # μm
+    dt = 0.01,            # s
+    t_max = 10.0          # s
+)
+
+# Run simulation
+systems = simulate(params)
+
+# Visualize the simulation
+visualize_sequence(systems, filename="diffusion.mp4")
+```
 """
 module InteractionDiffusion
 
@@ -12,7 +47,6 @@ using SMLMSim
 using Printf
 using CairoMakie
 
-
 include("types.jl")
 include("smoluchowski.jl")
 include("visualize.jl")
@@ -33,10 +67,15 @@ export
     # Analysis functions
     get_dimers,
     gen_dimer_images,
+    analyze_dimer_fraction,
 
+    # Visualization functions
     show_frame,
     visualize_sequence,
-    visualize_simulation
-
+    visualize_simulation,
+    
+    # Microscope image generation
+    gen_image,
+    gen_image_sequence
 
-end
+end

src/diffusion/dimer.jl

@@ -1,4 +1,3 @@
-
 """
     get_dimers(system::DiffusingMoleculeSystem)
 
@@ -9,6 +8,12 @@ Extract a new DiffusingMoleculeSystem containing only molecules in dimer state.
 
 # Returns
 - `DiffusingMoleculeSystem`: New system containing only dimers
+
+# Example
+```julia
+# Extract only dimers from a system
+dimer_system = get_dimers(system)
+```
 """
 function get_dimers(system::DiffusingMoleculeSystem)
     # Extract molecules in dimer state
@@ -35,31 +40,61 @@ Extract dimers from a sequence of system states.
 
 # Returns
 - `Vector{DiffusingMoleculeSystem}`: Sequence of dimer-only states
+
+# Example
+```julia
+# Run simulation
+params = SmoluchowskiParams()
+systems = simulate(params)
+
+# Extract dimers at each timepoint
+dimer_systems = get_dimers(systems)
+```
 """
 function get_dimers(systems::Vector{<:DiffusingMoleculeSystem})
     [get_dimers(system) for system in systems]
 end
 
 """
-    gen_dimer_images(systems::Vector{DiffusingMoleculeSystem}, psf::AbstractPSF; kwargs...)
+    gen_dimer_images(systems::Vector{DiffusingMoleculeSystem}, psf::AbstractPSF; 
+                    photons::Float64=1000.0, bg::Float64=5.0,
+                    frame_integration::Int=1, poisson_noise::Bool=true)
 
 Generate microscope images showing only dimers.
 
 # Arguments
 - `systems::Vector{DiffusingMoleculeSystem}`: Sequence of system states
-- `psf::PSF`: Point spread function model
+- `psf::AbstractPSF`: Point spread function model
 
-# Optional kwargs
+# Keyword Arguments
+- `photons::Float64=1000.0`: Base photon count for emitters
+- `bg::Float64=5.0`: Background photon count per pixel
 - `frame_integration::Int=1`: Number of frames to integrate
 - `poisson_noise::Bool=true`: Whether to add Poisson noise
 
 # Returns
 - `Array{Float64,3}`: Stack of dimer-only images [ny, nx, frames]
+
+# Example
+```julia
+# Run simulation
+params = SmoluchowskiParams()
+systems = simulate(params)
+
+# Generate images showing only dimers
+psf = Gaussian2D(0.15)
+dimer_images = gen_dimer_images(systems, psf; 
+                              photons=2000.0,
+                              frame_integration=5)
+```
 """
 function gen_dimer_images(systems::Vector{<:DiffusingMoleculeSystem}, psf::AbstractPSF;
-                         frame_integration::Int=1, poisson_noise::Bool=true)
+                        photons::Float64=1000.0, bg::Float64=5.0,
+                        frame_integration::Int=1, poisson_noise::Bool=true)
     dimer_systems = get_dimers(systems)
     gen_image_sequence(psf, dimer_systems; 
+                      photons=photons,
+                      bg=bg,
                       frame_integration=frame_integration,
                       poisson_noise=poisson_noise)
 end
@@ -74,6 +109,24 @@ Calculate the fraction of molecules in dimer state over time.
 
 # Returns
 - `Vector{Float64}`: Dimer fraction at each timepoint
+
+# Example
+```julia
+# Run simulation
+params = SmoluchowskiParams()
+systems = simulate(params)
+
+# Calculate dimer fraction over time
+dimer_fractions = analyze_dimer_fraction(systems)
+
+# Plot the results
+using Plots
+times = range(0, params.t_max, length=length(systems))
+plot(times, dimer_fractions, 
+     xlabel="Time (s)", 
+     ylabel="Fraction of molecules in dimers",
+     title="Dimer formation dynamics")
+```
 """
 function analyze_dimer_fraction(systems::Vector{<:DiffusingMoleculeSystem})
     map(systems) do system
@@ -83,3 +136,31 @@ function analyze_dimer_fraction(systems::Vector{<:DiffusingMoleculeSystem})
     end
 end
 
+"""
+    analyze_dimer_lifetime(systems::Vector{DiffusingMoleculeSystem})
+
+Analyze the lifetime distribution of dimers.
+
+# Arguments
+- `systems::Vector{DiffusingMoleculeSystem}`: Sequence of system states
+
+# Returns
+- `Vector{Float64}`: Distribution of dimer lifetimes
+
+# Note
+This function is not yet fully implemented.
+"""
+function analyze_dimer_lifetime(systems::Vector{<:DiffusingMoleculeSystem})
+    # Get time step from metadata
+    if !haskey(systems[1].metadata, "simulation_parameters")
+        error("System metadata missing simulation parameters")
+    end
+    
+    params = systems[1].metadata["simulation_parameters"]
+    dt = params.dt
+    
+    # TODO: Implement dimer lifetime tracking
+    @warn "Dimer lifetime analysis not yet fully implemented"
+    
+    return Float64[]
+end