3D Enzyme Cascade Simulation (MATLAB)

🌐 Language / ����

• 📚 Documentation: 3D Theory (English) | 理论说明（中文）
• ⚙️ Quick Start: Installation | Usage | Examples
• 📊 Features: Key Features | Algorithm | Visualization

1. Project Overview

This subproject implements a 3D Brownian dynamics simulator for a two-step enzyme cascade, extending the 2D framework to three dimensions while keeping a shared, dimension-agnostic core. It compares mineral-surface enzyme (MSE) localization against bulk distribution in 3D, and adds utilities for data export, automated testing, and interactive visualization in MATLAB.

Key features:

• Dimension-aware core that can run in 3D and reuse logic for 2D via a compatibility layer.
• Support for both MSE and bulk modes with heterogeneous diffusion and crowding inhibition.
• Multi-task parallel execution for running many independent configurations in parallel.
• Checkpoint-like batch execution and resumable 3D simulations.
• Unified export of MAT, CSV and JSON metadata for downstream analysis.
• Interactive 3D viewer for snapshots and shell statistics.

For the underlying physical and mathematical model, see 3D/docs/3d_model_theory.en.md and 3D/docs/3d_model_theory.md.

2. Repository Layout

All paths below are relative to this 3D/ directory.

• core/ – simulation core, configuration, RNG and utilities:
  • core/config3d/ – default configuration and helpers, for example default_config3d.m.
  • core/sim_core3d/ – 3D simulation loop and physics, for example simulate_once3d.m, diffusion_step3d.m, boundary_reflection3d.m.
  • core/utils/ – shared utilities (neighbor search, timers, cell lists), for example neighbor_celllist3d.m.
  • core/rng/ – random seed initialization via setup_rng.m.
  • core/legacy_2d/ – snapshot of the original 2D implementation, kept for regression and comparison only.
• export/ – data export helpers, for example save_results_mat.m, write_metadata3d.m, write_run_summary_csv.m.
• viz/ – 3D visualization tools such as plot_snapshot3d.m, plot_shell_dynamics3d.m and render_single_run_figures.m.
• scripts/ – entry-point scripts:
  • run_single_batch.m – single 3D simulation with export.
  • run_parallel_batch.m – parallel batch execution for one configuration.
  • run_fast_batch.m and run_sanity_single.m – light-weight examples and sanity checks.
  • example_multi_task_parallel.m – multi-task parallel execution with different configurations.
  • interactive_cli.m – interactive configuration, including multi-task parallel mode.
  • demo_viewer.m – convenience wrapper to open the 3D viewer on the latest run.
  • compare_legacy_2d.m – 3D core (run in 2D mode) vs legacy 2D regression script.
• tests/ – unit and smoke tests, including diffusion, boundary reflection, inhibition, GPU and parallel execution tests. Unified entry point: run_tests.m.
• docs/ – design notes and guides, including ARCHITECTURE.md, PARALLEL_EXECUTION_GUIDE.md and the 3D theory documents introduced above.

3. Requirements

• MATLAB R2019b or later (tested with newer versions).
• Recommended toolboxes:
  • Parallel Computing Toolbox – required for parfor-based batch execution and multi-task parallelism.
  • Statistics and Machine Learning Toolbox – recommended for some neighbor search backends.
• Optional: an NVIDIA GPU for GPU-accelerated neighbor search and larger systems.

On Windows, Linux or macOS you can run the project from a standard desktop installation of MATLAB with the toolboxes above.

4. Quick Start

4.1 Add the project to the MATLAB path

In MATLAB, change the current folder to the 3D/ directory and add the relevant subfolders:

addpath(pwd);                     % 3D/
addpath(fullfile(pwd, 'core'));
addpath(fullfile(pwd, 'core', 'config3d'));
addpath(fullfile(pwd, 'core', 'sim_core3d'));
addpath(fullfile(pwd, 'core', 'utils'));
addpath(fullfile(pwd, 'export'));
addpath(fullfile(pwd, 'viz'));
addpath(fullfile(pwd, 'scripts'));

4.2 Run a single 3D simulation

run_single_batch;

This runs a default 3D MSE vs bulk comparison and writes results to the out/ directory (MAT files, CSV exports, and figures).

4.3 Run the full test suite

tests/run_tests;

This executes unit tests for diffusion, boundary reflection, inhibition logic, neighbor list construction, GPU execution (if available), and configuration sanity checks.

5. Example Workflows

• MSE vs bulk comparison: adjust the configuration in core/config3d/default_config3d.m and re-run run_single_batch.
• Batch parameter sweep: use scripts/run_parallel_batch.m or scripts/example_multi_task_parallel.m.
• Checkpoint / resume experiments: see core/sim_core3d/resume_from_checkpoint3d.m and smoke tests in tests/.
• Visualization only: call scripts/demo_viewer.m to open the 3D viewer on the latest run in out/single.

6. License

This 3D module is released under the MIT License, consistent with the 2D project.
See the LICENSE file in this directory for full terms and citation guidelines.