ankitgupta83/SpectralKoopman: SKA1.0.0

Abstract

SpectralKoopman This repository provides an implementation of the Spectral Koopman Approximation (SKA) method for stochastic reaction networks (SRNs). The code accompanies the manuscript: A spectral framework for revealing the hidden low-dimensional structure in stochastic reaction networks Ankit Gupta and Mustafa Khammash Overview The implementation is primarily written in Python, with selected stochastic-simulation routines implemented in C++ and CUDA C++. When a compatible NVIDIA GPU is available, the code automatically uses GPU execution to estimate iterated resolvents and long-term averages. Otherwise, these computations are performed on the CPU. No specialised hardware is required for CPU execution. A CUDA-compatible NVIDIA GPU is optional and can substantially accelerate the stochastic simulations. Repository structure | File or directory | Description | |---|---| | analysis_configuration.json | Specifies the reaction network, initial state, simulation settings, decay-mode estimation settings, Koopman-operator settings, sensitivity-analysis settings and spectral-analysis settings. | | output_configuration.json | Specifies which analyses and plots are generated, including Koopman trajectories, SSA comparisons, parameter sensitivities, cross-spectral densities and optional movies. | | main.py | Main entry point. It reads the two JSON configuration files from the repository root, runs the requested analyses and saves the outputs. | | ReactionNetworkClass.py | Defines the ReactionNetworkDefinition base class for stochastic reaction networks and generates the C++ and CUDA C++ simulation code. | | ReactionNetworkExamples.py | Contains the reaction-network examples used in the manuscript. New networks can be added by inheriting from ReactionNetworkDefinition. | | IteratedResolventEstimator.py | Estimates iterated resolvents and their differences. | | decayModeEstimator.py | Estimates decay modes from resolvent data using constrained numerical optimisation. | | KoopmanEstimator.py | Estimates the coefficients in the spectral expansion of the Koopman operator. | | simulationRoutines.py | Provides stochastic simulation algorithm (SSA) routines and coupled finite-difference (CFD) simulations for sensitivity estimation. | | stationaryDistributionEstimator.py | Produces a crude approximation of the stationary distribution. | | sensitivityEstimation.py | Estimates parameter-sensitivity trajectories. | | CSD_Estimation.py | Estimates cross-spectral densities using SKA and SSA–DFT. | | plotting.py | Generates decay-mode, trajectory, sensitivity and cross-spectral-density plots and optional movies. | | lib/ | Contains the C++ and CUDA C++ header files used by the generated simulation code. | | bin/ | Created automatically at runtime and used for generated and compiled C++/CUDA files. | | Results/ | Created automatically at runtime and used for numerical results, plots and movies. | System requirements Required software The software was run using the following versions: Operating system: Ubuntu 22.04 Python: 3.8.8 GCC/g++: 11.4.0 NumPy: 1.20.1 SciPy: 1.10.1 scikit-learn: 0.24.1 pandas: 1.2.4 Matplotlib: 3.7.5 Seaborn: 0.11.1 A working C++ compiler accessible through the command g++ is required because the CPU simulation routines are generated and compiled at runtime. A LaTeX installation is required with the current plotting settings because plotting.py uses Matplotlib with text.usetex=True. Alternatively, users may set text.usetex=False in plotting.py. Optional software and hardware GPU execution requires: an NVIDIA CUDA-compatible GPU; NVIDIA CUDA Toolkit 12.6 (nvcc 12.6.85 in the tested environment); a compatible NVIDIA driver. Movie generation additionally requires FFmpeg, because Matplotlib uses the FFmpeg writer to create MP4 files. Tested environments GPU-enabled execution GPU-enabled execution was tested on: Ubuntu 22.04; Python 3.10.12; GCC/g++ 11.4.0; NVIDIA CUDA Toolkit 12.6 (nvcc 12.6.85); NVIDIA driver 560.35.05; NVIDIA RTX 4500 Ada Generation GPU with approximately 24 GB of memory. CPU execution The CPU demonstration described below was run on a MacBook Pro equipped with a 2.4 GHz 8-core Intel Core i9 processor. No specialised hardware is required for CPU execution. Installation Clone the repository: git clone https://github.com/ankitgupta83/SpectralKoopman.git cd SpectralKoopman Create and activate an isolated Python environment. For example: python3 -m venv .venv source .venv/bin/activate python3 -m pip install --upgrade pip Install the pinned dependencies supplied with the repository: python3 -m pip install -r requirements.txt The C++ and CUDA C++ simulation code is generated and compiled automatically when the program is run. No separate compilation step is required. Typical installation time: Creating a clean Python virtual environment and installing the required Python packages typically takes approximately 5 minutes on a standard desktop computer with a broadband internet connection, provided that Python and the required system-level dependencies are already installed. Installation of optional system software, such as the NVIDIA CUDA Toolkit, LaTeX or FFmpeg, is not included in this estimate. Running the software The program reads analysis_configuration.json and output_configuration.json directly from the repository root. Run it using: python3 main.py The program creates an output directory of the form: ./Results/ / where is set in analysis_configuration.json. Configuration Analysis configuration Edit analysis_configuration.json to specify: network_name: the name of a reaction-network class defined in ReactionNetworkExamples.py; output_folder_name: the directory name used under ./Results/; initial_state: the initial molecular-count vector; stationary-distribution sampling settings; decay-mode and iterated-resolvent estimation settings; Koopman-operator estimation settings; sensitivity-analysis settings; spectral-analysis settings. Output configuration Edit output_configuration.json to select: whether Koopman trajectories are generated; whether SKA trajectories are compared with SSA; whether parameter-sensitivity analysis is performed; whether sensitivity estimates are compared with CFD; whether cross-spectral densities are generated; whether SKA spectra are compared with SSA–DFT; which functions and parameters are plotted; whether an MP4 movie of the evolving spectral density is created. Demo The current analysis_configuration.json and output_configuration.json files define a self-contained simulation example; no external dataset is required. Run the demonstration from the repository root: python3 main.py On a MacBook Pro equipped with a 2.4 GHz 8-core Intel Core i9 processor, the demonstration takes less than 3 minutes. The expected console output is provided in demo_output.txt. Numerical results and plots are written to the output directory specified by output_folder_name. For the supplied self-regulatory gene-expression demonstration, the expected directory is: ./Results/self_regulatory_gene_expression/ The generated files include numerical estimates and PDF plots requested through output_configuration.json. Because the simulations use randomly generated trajectories, the numerical values may vary slightly between runs, although the qualitative results and reported approximation accuracy should remain consistent. Using a different reaction network To analyse another stochastic reaction network: Define a new class in ReactionNetworkExamples.py by inheriting from ReactionNetworkDefinition. Specify the reactant and product matrices, parameter values, reaction propensities, species labels and output functions. Set network_name in analysis_configuration.json to the name of the new class. Set initial_state and output_folder_name. Select the required analyses in analysis_configuration.json and output_configuration.json. Run: python3 main.py Retrieve the generated results from: ./Results/ / Expected outputs Depending on the selected configuration, the software may generate: an approximation of the stationary distribution; estimated decay modes and associated approximation errors; SKA moment trajectories; SSA comparison trajectories; parameter-sensitivity trajectories; cross-spectral-density estimates; PDF figures; an MP4 movie of evolving spectral densities. The precise set of outputs is controlled by output_configuration.json. Reproducing manuscript results The reaction-network definitions used in the manuscript are included in ReactionNetworkExamples.py. Licence This software is distributed under the GNU General Public License v3.0. See LICENSE for details. Citation When using this software, please cite: Ankit Gupta and Mustafa Khammash, "A spectral framework for revealing the hidden low-dimensional structure in stochastic reaction networks", manuscript accompanying this repository. The citation should be updated with the journal reference and DOI after publication.