AMS-BP 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

AMS_BP/gui/help_docs/channels_help.md

@@ -0,0 +1,78 @@
+# Channels Configuration Help
+
+This section allows you to define the optical channels used in the simulation, including filters for excitation and emission as well as split efficiencies.
+
+## Fields
+
+### `num_of_channels`
+- **Type**: Integer
+- **Description**: Number of optical channels. Each channel is assigned its own tab.
+
+### `channel_names`
+- **Type**: Array of Strings
+- **Description**: Names of each channel (e.g., `"Channel 1"`, `"GFP"`, `"Cy5"`). Must be unique.
+
+### `split_efficiency`
+- **Type**: Array of Numbers
+- **Range**: `0.0` – `1.0`
+- **Description**: Efficiency of the beam splitter for each channel. Determines what fraction of signal is passed to the channel.
+
+---
+
+## Filter Set Configuration
+
+Each channel defines a **filter set** with excitation and emission filters.
+
+### `filter_set_name`
+- **Type**: String
+- **Description**: Descriptive name for the filter set.
+
+### `filter_set_description`
+- **Type**: String
+- **Description**: Optional details about the purpose of the filter set.
+
+---
+
+## Excitation Filter
+
+### `name`
+- **Type**: String
+- **Description**: Name of the excitation filter.
+
+### `type`
+- **Type**: String
+- **Options**: `"bandpass"`, `"allow_all"`
+- **Description**:
+  - `"bandpass"` filters light around a central wavelength.
+  - `"allow_all"` passes all wavelengths without filtering.
+
+### `center_wavelength` *(only if type is `"bandpass"`)*  
+- **Type**: Integer  
+- **Unit**: Nanometers (nm)  
+- **Description**: Central wavelength of the bandpass filter.
+
+### `bandwidth` *(only if type is `"bandpass"`)*  
+- **Type**: Integer  
+- **Unit**: Nanometers (nm)  
+- **Description**: Width of the bandpass range.
+
+### `transmission_peak` *(only if type is `"bandpass"`)*  
+- **Type**: Float  
+- **Range**: `0.0` – `1.0`  
+- **Description**: Maximum transmission efficiency.
+
+### `points`
+- **Type**: Integer  
+- **Description**: Number of discrete sampling points in the filter curve.
+
+---
+
+## Emission Filter
+
+Identical in structure to the Excitation filter.
+
+### Notes:
+- `"allow_all"` disables wavelength-specific fields.
+- Bandpass filters should be configured carefully to avoid overlap between channels.
+- Points determine how finely the spectrum is resolved during simulation.
+

AMS_BP/gui/help_docs/condensate_help.md

@@ -0,0 +1,59 @@
+# Condensate Configuration Help
+
+This section defines parameters for **condensate droplets** within the simulation. Each tab corresponds to a molecule type, and each type can have multiple condensates.
+
+---
+
+## Molecule Count
+
+### `Number of Molecule Types`
+- **Type**: Integer
+- **Description**: The number of different molecule types in the simulation. Each will be assigned its own tab.
+
+---
+
+## Per-Molecule Condensate Parameters
+
+### `Number of Condensates`
+- **Type**: Integer
+- **Description**: The number of condensates of this molecule type.
+
+Each condensate defines the following:
+
+### `Initial Center`
+- **Type**: List of 3 Floats `[x, y, z]`
+- **Unit**: Micrometers (µm)
+- **Description**: The spatial center of the condensate in 3D.
+
+### `Initial Scale`
+- **Type**: Float
+- **Unit**: Micrometers (µm)
+- **Description**: The initial physical size (radius or diameter) of the condensate.
+
+### `Diffusion Coefficient`
+- **Type**: Float
+- **Unit**: µm²/s
+- **Description**: The diffusion coefficient for the condensate particles.
+
+### `Hurst Exponent`
+- **Type**: Float
+- **Range**: `0.0` – `1.0`
+- **Description**: Controls the memory of the random walk. `0.5` = standard Brownian motion. Values above or below indicate persistent or antipersistent motion.
+
+---
+
+## Density Difference
+
+### `Density Difference`
+- **Type**: Float
+- **Description**: Represents the relative density difference between the condensate and its surrounding medium.
+- **Location**: Set **per molecule type** (i.e., one value per tab).
+
+---
+
+### Notes
+
+- All condensate values are grouped per molecule type.
+- You may define different numbers of condensates for different molecule types.
+- This module supports nested array generation for initialization within the simulation core.
+

AMS_BP/gui/help_docs/detector_help.md

@@ -0,0 +1,57 @@
+# Camera Configuration Help
+
+This section configures the camera model used in the simulation. Each field controls aspects of detection, noise, resolution, and efficiency.
+
+## Fields
+
+### `type`
+- **Type**: `String`
+- **Options**: `"CMOS"`
+- **Description**: Specifies the camera sensor model. Only CMOS is currently supported in the UI. Programmatically you also have access to EMCCD.
+
+### `pixel_count`
+- **Type**: `Array of Integers`
+- **Shape**: `[width, height]`
+- **Description**: Defines the resolution of the sensor in pixels. Affects image dimensions.
+
+### `pixel_detector_size`
+- **Type**: `Number`
+- **Units**: `micrometers (μm)`
+- **Description**: Physical size of a single pixel. Affects spatial resolution and magnification scaling.
+
+### `magnification`
+- **Type**: `Integer`
+- **Description**: Optical magnification factor applied to the image.
+
+### `dark_current`
+- **Type**: `Number`
+- **Units**: `electrons/pixel/second`
+- **Description**: Rate at which thermal electrons accumulate in each pixel without illumination.
+
+### `readout_noise`
+- **Type**: `Number`
+- **Units**: `electrons RMS`
+- **Description**: Baseline electronic noise added during readout.
+
+### `bit_depth`
+- **Type**: `Integer`
+- **Description**: Bit depth of the analog-to-digital converter. Controls the dynamic range of intensity.
+
+### `sensitivity`
+- **Type**: `Number`
+- **Units**: `electrons/ADU`
+- **Description**: Defines how many electrons are required to register one analog-digital unit (ADU) in the image.
+
+### `base_adu`
+- **Type**: `Integer`
+- **Description**: The base offset in ADUs added to all pixel values.
+
+### `binning_size`
+- **Type**: `Integer`
+- **Description**: Spatial binning size used to combine adjacent pixels. Common values are 1 (no binning), 2 (2x2 binning), etc.
+
+### `quantum_efficiency`
+- **Type**: `Array of [wavelength, efficiency] pairs`
+- **Units**: `nm`, `[0-1]`
+- **Description**: Describes the wavelength-dependent efficiency of the camera. Higher values mean more photons are converted to signal.
+

AMS_BP/gui/help_docs/experiment_help.md

@@ -0,0 +1,92 @@
+# Experiment Configuration Help
+
+This section defines the structure of the **experiment** to be simulated. It includes information about the type of acquisition, the z-plane positions, and the laser activation strategy.
+
+---
+
+## General Fields
+
+### `name`
+- **Type**: String
+- **Description**: The name of the experiment. This will be used to label output files and for documentation purposes.
+
+### `description`
+- **Type**: String
+- **Description**: A short description of the experiment setup or purpose.
+
+---
+
+## Experiment Type
+
+### `experiment_type`
+- **Type**: String
+- **Enum**: `["time-series", "z-stack"]`
+- **Description**: Determines the acquisition mode:
+  - `time-series`: Single z-plane acquired over time.
+  - `z-stack`: Multiple z-planes acquired in a single timepoint sweep.
+
+---
+
+## Z Positions
+
+### `z_position`
+- **Type**:
+  - Float for `time-series`
+  - List of Floats for `z-stack`
+- **Unit**: Micrometers (µm)
+- **Description**:
+  - In `time-series`, a single z-position is specified.
+  - In `z-stack`, multiple z-positions are given, each corresponding to a slice in the stack.
+
+---
+
+## Laser Activation
+
+### `laser_names_active`
+- **Type**: List of Strings
+- **Description**: Names of the lasers to be activated during this experiment. These must match the names defined in the laser configuration section.
+
+### `laser_powers_active`
+- **Type**: List of Floats
+- **Unit**: Watts
+- **Description**: The power levels for each laser, in the same order as `laser_names_active`.
+
+### `laser_positions_active`
+- **Type**: List of Lists `[x, y, z]`
+- **Unit**: Micrometers (µm)
+- **Description**: The position of each active laser beam in space. Each laser has a position defined as `[x, y, z]`.
+
+---
+
+## XY Offset
+
+### `xyoffset`
+- **Type**: List `[x, y]`
+- **Unit**: Micrometers (µm)
+- **Description**: The lateral offset applied to the sample plane during acquisition.
+
+---
+
+## Time Parameters (only for `z-stack`)
+
+### `exposure_time`
+- **Type**: Integer
+- **Unit**: Milliseconds (ms)
+- **Description**: Exposure duration per z-slice.
+
+### `interval_time`
+- **Type**: Integer
+- **Unit**: Milliseconds (ms)
+- **Description**: Time between capturing consecutive z-slices.
+
+> ⚠️ These time fields are only used for `z-stack` experiments.  
+> In `time-series` mode, time control should be handled globally under **Global Parameters**.
+
+---
+
+### Notes
+
+- The number of `laser_names_active`, `laser_powers_active`, and `laser_positions_active` must match.
+- Laser names must be defined in the Laser Configuration section.
+- For `z-stack`, the total time per stack is `exposure_time × len(z_position) + interval_time × (len(z_position) - 1)`.
+

AMS_BP/gui/help_docs/fluorophore_help.md

@@ -0,0 +1,128 @@
+# Fluorophore Configuration Help
+
+This section defines the **fluorophores** used in the simulation, including their photophysical states and transition dynamics.
+
+Each fluorophore can contain one or more states, and transitions between them. States can be fluorescent, dark (non-emissive), or bleached (permanently off).
+
+---
+
+## Top-Level Fields
+
+### `num_of_fluorophores`
+- **Type**: Integer
+- **Description**: Total number of distinct fluorophore types.
+
+### `fluorophore_names`
+- **Type**: List of Strings
+- **Description**: Names identifying each fluorophore. These must be unique.
+
+---
+
+## Per-Fluorophore Fields
+
+Each fluorophore has its own section named after its `name`.
+
+### `name`
+- **Type**: String
+- **Description**: Redundant copy of the fluorophore name.
+
+### `initial_state`
+- **Type**: String
+- **Description**: The state in which each fluorophore begins the simulation. Must match one of the defined state names.
+
+---
+
+## States Section
+
+Each fluorophore contains a `states` section, defining its possible photophysical states.
+
+### `states`
+- **Type**: Dictionary
+- **Key**: State name (e.g., `"on"`, `"off"`, `"bleached"`)
+- **Value**: Dictionary with the following fields:
+
+#### `name`
+- **Type**: String
+- **Description**: Name of the state.
+
+#### `state_type`
+- **Type**: Enum
+- **Options**: `"fluorescent"`, `"dark"`, `"bleached"`
+- **Description**: Type of the photophysical state.
+
+#### If `state_type == "fluorescent"`, the following fields are required:
+
+##### `quantum_yield`
+- **Type**: Float
+- **Range**: [0, 1]
+- **Description**: Quantum yield of emission.
+
+##### `extinction_coefficient`
+- **Type**: Float
+- **Unit**: M⁻¹·cm⁻¹
+- **Description**: Molar extinction coefficient for light absorption.
+
+##### `fluorescent_lifetime`
+- **Type**: Float
+- **Unit**: Seconds
+- **Description**: Mean lifetime of the fluorophore before emitting a photon.
+
+##### `excitation_spectrum`
+- **Type**: Dictionary
+- **Fields**:
+  - `wavelengths`: List of Floats (nm)
+  - `intensities`: List of Floats (normalized to [0, 1])
+- **Description**: Defines the excitation efficiency across the spectrum.
+
+##### `emission_spectrum`
+- **Type**: Dictionary
+- **Fields**:
+  - `wavelengths`: List of Floats (nm)
+  - `intensities`: List of Floats (normalized to [0, 1])
+- **Description**: Defines the emission intensity across the spectrum.
+
+---
+
+## Transitions Section
+
+Each fluorophore can also define transitions between states.
+
+### `transitions`
+- **Type**: Dictionary
+- **Key**: Transition label (e.g., `"on_to_off"`)
+- **Value**: Dictionary with:
+
+#### `from_state`, `to_state`
+- **Type**: Strings
+- **Description**: Names of the source and target states.
+
+#### `photon_dependent`
+- **Type**: Boolean
+- **Description**: Whether this transition depends on light absorption.
+
+#### If `photon_dependent == False`:
+
+##### `base_rate`
+- **Type**: Float
+- **Unit**: s⁻¹
+- **Description**: Constant rate of transition (Poisson process).
+
+#### If `photon_dependent == True`:
+
+##### `spectrum`
+- **Type**: Dictionary
+- **Fields**:
+  - `wavelengths`: List of Floats (nm)
+  - `intensities`: List of Floats (normalized)
+  - `quantum_yield`: Float [0, 1]
+  - `extinction_coefficient`: Float (M⁻¹·cm⁻¹)
+- **Description**: Defines the absorption characteristics that trigger the transition.
+
+---
+
+## Notes
+
+- State and transition names must be unique within a fluorophore.
+- Spectral data should cover the same wavelength range for excitation and emission (typically 300–800 nm).
+- Transitions allow for modeling of photoswitching, blinking, and photobleaching.
+

AMS_BP/gui/help_docs/general_help.md

@@ -0,0 +1,43 @@
+# General Configuration Help
+
+This section defines the global settings that apply to **all units and measurements** throughout the simulation.
+
+These values are typically fixed and should not be changed unless the simulation framework explicitly supports it.
+
+---
+
+## Fields
+
+### `version`
+- **Type**: String
+- **Format**: `X.Y` (e.g., `0.1`, `1.0`)
+- **Description**: Version of the configuration schema being used. Ensures compatibility between your configuration file and the simulation engine.
+
+---
+
+### `length_unit`
+- **Type**: String
+- **Allowed Values**: `"um"` (micrometers)
+- **Description**: The base unit of length for the simulation. All spatial dimensions (e.g., cell size, laser beam width, positions) are expressed in micrometers.
+
+---
+
+### `time_unit`
+- **Type**: String
+- **Allowed Values**: `"ms"` (milliseconds)
+- **Description**: The unit of time for all time-related parameters like exposure, interval, and simulation durations.
+
+---
+
+### `diffusion_unit`
+- **Type**: String
+- **Allowed Values**: `"um^2/s"`
+- **Description**: The unit for diffusion coefficients. All diffusion values are given in square micrometers per second.
+
+---
+
+## Notes
+
+- These units are **not editable** in most configurations and are standardized to simplify parameter consistency.
+- All widgets and backend systems interpret numeric values based on these settings.
+

AMS_BP/gui/help_docs/global_help.md

@@ -0,0 +1,47 @@
+# Global Parameters Help
+
+This section defines the overarching timing and physical layout parameters of the simulation environment. These values affect **all molecules and the simulation timeline**.
+
+---
+
+## Fields
+
+### `sample_plane_dim`
+- **Type**: Array of Numbers `[width, height]`
+- **Units**: Micrometers (`μm`)
+- **Description**: Specifies the width and height of the simulation's imaging plane. This defines the observable region for molecule motion and fluorescence.
+
+---
+
+### `cycle_count`
+- **Type**: Integer
+- **Description**: The number of complete exposure–interval cycles to simulate. For example, a cycle count of 5 with 100ms exposure and 50ms interval simulates a total of 750ms.
+
+---
+
+### `exposure_time`
+- **Type**: Integer
+- **Units**: Milliseconds (`ms`)
+- **Description**: Duration for which the camera exposes per frame. Affects motion blur and signal strength.
+
+---
+
+### `interval_time`
+- **Type**: Integer
+- **Units**: Milliseconds (`ms`)
+- **Description**: Time between exposures. Combined with exposure time, it defines the total frame interval.
+
+---
+
+### `oversample_motion_time`
+- **Type**: Integer
+- **Units**: Milliseconds (`ms`)
+- **Description**: The time resolution used for simulating motion in a sub-frame manner. Useful for accurate motion blur or faster dynamics within a single exposure.
+
+---
+
+## Notes
+
+- Exposure and interval times together define the temporal resolution of the simulation.
+- Oversample motion time enables fine-grained molecule dynamics between frames.
+

AMS_BP/gui/help_docs/laser_help.md

@@ -0,0 +1,76 @@
+# Laser Configuration Help
+
+This section allows you to define the properties of each laser used in the simulation. Each laser must have a unique name and type, and may include physical and optical characteristics that influence excitation and activation.
+
+---
+
+## General Fields
+
+### `active`
+- **Type**: Array of Strings
+- **Description**: The list of lasers that are active during the experiment. These names must match the defined laser entries.
+
+---
+
+## Laser-Specific Parameters
+
+Each laser has a dedicated section and includes the following fields:
+
+### `name`
+- **Type**: String
+- **Description**: Unique identifier for the laser. This name is used to associate laser settings with experiment configurations.
+
+---
+
+### `type`
+- **Type**: Enum [`widefield`, `gaussian`, `hilo`]
+- **Description**:
+  - `widefield`: Uniform illumination across the entire plane.
+  - `gaussian`: Focused beam with Gaussian profile.
+  - `hilo`: Highly inclined and laminated optical sheet—oblique angle illumination for reduced background.
+
+---
+
+### `preset`
+- **Type**: String
+- **Description**: An optional label to describe this laser's use case (e.g., `"default 488nm"`). Does not affect simulation directly.
+
+---
+
+### `parameters`
+
+#### `power`
+- **Type**: Float
+- **Units**: Watts (W)
+- **Description**: The power of the laser beam. Impacts excitation intensity and photophysics.
+
+#### `wavelength`
+- **Type**: Integer
+- **Units**: Nanometers (nm)
+- **Description**: The wavelength of emitted light from the laser. Should match fluorophore excitation peaks.
+
+#### `beam_width`
+- **Type**: Float
+- **Units**: Micrometers (`μm`)
+- **Description**: The width of the laser beam in the focal plane. Relevant for spatial precision.
+
+#### `numerical_aperture`
+- **Type**: Float
+- **Description**: The NA of the illumination optics. Impacts the cone angle and axial resolution.
+
+#### `refractive_index`
+- **Type**: Float
+- **Description**: The refractive index of the medium the laser is passing through (usually water or oil immersion).
+
+#### `inclination_angle`
+- **Type**: Float (only for `hilo`)
+- **Units**: Degrees
+- **Description**: The angle of incidence for HiLo illumination.
+
+---
+
+## Notes
+
+- **Confocal Mode**: If confocal mode is enabled via PSF settings, all lasers are automatically forced to use Gaussian beams.
+- The `inclination_angle` is only enabled when `type` is set to `"hilo"`.
+

AMS_BP/gui/help_docs/molecule_help.md

@@ -0,0 +1,78 @@
+# Molecule Configuration Help
+
+This section allows you to define the behavior and motion characteristics of each molecular species in the simulation. Each molecule type can follow different track models and include multiple diffusive or subdiffusive states.
+
+---
+
+## `num_molecules`
+- **Type**: Array of Integers
+- **Description**: The number of molecules for each defined type. The number of entries in this array defines the number of molecule types in the simulation.
+
+---
+
+## `track_type`
+- **Type**: Array of Strings
+- **Enum**: `["constant", "fbm"]`
+- **Description**:
+  - `constant`: Molecules exhibit fixed diffusion.
+  - `fbm` (Fractional Brownian Motion): Molecules follow anomalous diffusion governed by a Hurst exponent.
+
+---
+
+## `diffusion_coefficient`
+- **Type**: Array of Arrays of Floats
+- **Units**: `μm²/s`
+- **Description**: Specifies the diffusion coefficients for each molecule type. Each type can have one or more diffusion states.
+
+---
+
+## `diffusion_track_amount`
+- **Type**: Array of Arrays of Floats
+- **Description**: Initial distribution (probabilities) of molecules across each diffusion state. Must sum to 1.0 per molecule type.
+
+---
+
+## `hurst_exponent`
+- **Type**: Array of Arrays of Floats
+- **Range**: [0, 1]
+- **Description**: Only used for `fbm` track types. Defines the Hurst exponents controlling subdiffusive behavior.
+
+---
+
+## `hurst_track_amount`
+- **Type**: Array of Arrays of Floats
+- **Description**: Initial distribution of molecules across each Hurst exponent state. Must sum to 1.0. Ignored for `constant` track types.
+
+---
+
+## `allow_transition_probability`
+- **Type**: Array of Booleans
+- **Description**: Whether molecules of each type can switch between diffusion or hurst states during the simulation.
+
+---
+
+## `transition_matrix_time_step`
+- **Type**: Array of Integers
+- **Units**: `ms`
+- **Description**: The timestep interval at which transitions between states are evaluated. Only relevant when `allow_transition_probability` is `true`.
+
+---
+
+## `diffusion_transition_matrix`
+- **Type**: Array of 2D Arrays (Per Molecule Type)
+- **Description**: Transition probability matrices for diffusion coefficients. Each row must sum to 1. Only used if transitions are allowed.
+
+---
+
+## `hurst_transition_matrix`
+- **Type**: Array of 2D Arrays (Per Molecule Type)
+- **Description**: Transition probability matrices for hurst states. Only used for `fbm` track types and when transitions are allowed.
+
+---
+
+## Notes
+
+- If `track_type` is `constant`, the hurst-related fields will be ignored and hidden in the UI.
+- If a molecule type has only one state, the associated transition matrix is a 1×1 matrix with value 1.0.
+- State probability fields (`diffusion_track_amount`, `hurst_track_amount`) should match the number of corresponding states.
+

AMS_BP/gui/help_docs/output_help.md

@@ -0,0 +1,5 @@
+## Saving Instructions
+
+- **Output Path**: Directory to store results. Can be absolute or relative.
+- **Output Name**: Filename prefix for the saved output.
+- **Subsegment Type / Number**: Reserved for future implementation.