sopsim 0.2.0__tar.gz

sopsim-0.2.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include sopsim/mat_files *.mat
+recursive-include sopsim/web_dist *

sopsim-0.2.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: sopsim
+Version: 0.2.0
+Summary: SOPSim simulation library
+Author: Olaolu Olugbenle, Dr. William Annan
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: tqdm
+Requires-Dist: shapely
+Requires-Dist: matplotlib
+Requires-Dist: fastapi
+Requires-Dist: uvicorn[standard]
+Requires-Dist: pydantic
+Requires-Dist: python-dotenv
+
+# SOPSim
+
+SOPSim is a Python simulation package for investigating SOP pattern formation. You can choose to use it in one of four ways:
+
+1. The official SOPSim website
+2. As a Command line tool
+3. As a website, local to your computer
+4. As a Python API
+
+Each method is explained in detail below.
+
+## 1. The official SOPSim website
+
+The official SOPSim website is available at (*link coming soon*).
+
+## 2. As a Command line tool
+
+Inside your command line, type:
+
+```bash
+pip install -i https://test.pypi.org/simple/ sopsim==0.1.6
+```
+
+to install the package.
+
+Use this command below to run a single simulation:
+
+```bash
+sopsim run --nc 4 --filopodia-type A --filopodia-life-time 10 --out-dir output
+```
+
+In this specific example, this command will also generate plots and metadata to a folder called `output`.
+
+For help, run:
+
+```bash
+sopsim run -h
+```
+
+## 3. As a website, local to your computer
+
+After installing SOPSim with `pip install`, you can start the local web app with:
+
+```bash
+sopsim serve
+```
+
+Once you run this, copy the link and paste it into your browser. The link will show up in your terminal and will start with:
+```bash
+http://...
+```
+
+For help, run:
+
+```bash
+sopsim serve -h
+```
+
+## 4. As a Python API
+
+Assuming you have Python and the `sopsim` library installed, create a new Python script and add the following code:
+
+```python
+from sopsim import sopsim
+
+if __name__ == '__main__':
+    results = sopsim(Nc=4, filopodia_type="A", filopodia_life_time=10)
+    print(results["FData"])
+```
+
+Note: In its current version, using the API does not allow users to view plots.
+
+<!-- ## Sanity Checks
+
+By default, SOPSim uses NumPy's random number generator, so repeated runs with the same inputs can still produce different results.
+
+For a deterministic legacy comparison, use the bundled MATLAB reference matrices in this way:
+
+
+### Command Line
+```bash
+sopsim run --nc 4 --use-mat-files --out-dir output
+```
+
+### Website Local to your Computer
+Tick the "Use bundled legacy MAT files" checkbox
+
+### Python API (OLAOLU: MAKE SURE TO TEST THIS)
+```python
+from sopsim import sopsim
+
+results = sopsim(Nc=4, use_mat_files=True)
+print(results["FData"])
+``` -->
+
+### *Input Values*
+
+The repo enforces these input rules:
+
+| Input | Allowed values |
+| --- | --- |
+| `Nc` (Number of cells per row in final square tissue*) | Integer `>= 1` |
+| `filopodia_type` | One of `A`, `B`, `C`, `D`. Default = `A` |
+| `filopodia_life_time` | Integer `>= 1`. Default = `10` |
+<!-- | `use_mat_files` | `true` / `false`, only valid when `Nc = 4` | -->
+
+Important:
+
+<!-- - `--use-mat-files` is only supported when `Nc=4`
+- This mode is the best option when you want the same starting RNG state used in the legacy MATLAB workflow
+- For other `Nc` values, the simulation uses fresh random draws each run -->
+- *`Nc = 4` implies a 4x4 tissue
+- `Nc>=10` can take many hours to run, so start smaller when testing

sopsim-0.2.0/README.md

@@ -0,0 +1,113 @@
+# SOPSim
+
+SOPSim is a Python simulation package for investigating SOP pattern formation. You can choose to use it in one of four ways:
+
+1. The official SOPSim website
+2. As a Command line tool
+3. As a website, local to your computer
+4. As a Python API
+
+Each method is explained in detail below.
+
+## 1. The official SOPSim website
+
+The official SOPSim website is available at (*link coming soon*).
+
+## 2. As a Command line tool
+
+Inside your command line, type:
+
+```bash
+pip install -i https://test.pypi.org/simple/ sopsim==0.1.6
+```
+
+to install the package.
+
+Use this command below to run a single simulation:
+
+```bash
+sopsim run --nc 4 --filopodia-type A --filopodia-life-time 10 --out-dir output
+```
+
+In this specific example, this command will also generate plots and metadata to a folder called `output`.
+
+For help, run:
+
+```bash
+sopsim run -h
+```
+
+## 3. As a website, local to your computer
+
+After installing SOPSim with `pip install`, you can start the local web app with:
+
+```bash
+sopsim serve
+```
+
+Once you run this, copy the link and paste it into your browser. The link will show up in your terminal and will start with:
+```bash
+http://...
+```
+
+For help, run:
+
+```bash
+sopsim serve -h
+```
+
+## 4. As a Python API
+
+Assuming you have Python and the `sopsim` library installed, create a new Python script and add the following code:
+
+```python
+from sopsim import sopsim
+
+if __name__ == '__main__':
+    results = sopsim(Nc=4, filopodia_type="A", filopodia_life_time=10)
+    print(results["FData"])
+```
+
+Note: In its current version, using the API does not allow users to view plots.
+
+<!-- ## Sanity Checks
+
+By default, SOPSim uses NumPy's random number generator, so repeated runs with the same inputs can still produce different results.
+
+For a deterministic legacy comparison, use the bundled MATLAB reference matrices in this way:
+
+
+### Command Line
+```bash
+sopsim run --nc 4 --use-mat-files --out-dir output
+```
+
+### Website Local to your Computer
+Tick the "Use bundled legacy MAT files" checkbox
+
+### Python API (OLAOLU: MAKE SURE TO TEST THIS)
+```python
+from sopsim import sopsim
+
+results = sopsim(Nc=4, use_mat_files=True)
+print(results["FData"])
+``` -->
+
+### *Input Values*
+
+The repo enforces these input rules:
+
+| Input | Allowed values |
+| --- | --- |
+| `Nc` (Number of cells per row in final square tissue*) | Integer `>= 1` |
+| `filopodia_type` | One of `A`, `B`, `C`, `D`. Default = `A` |
+| `filopodia_life_time` | Integer `>= 1`. Default = `10` |
+<!-- | `use_mat_files` | `true` / `false`, only valid when `Nc = 4` | -->
+
+Important:
+
+<!-- - `--use-mat-files` is only supported when `Nc=4`
+- This mode is the best option when you want the same starting RNG state used in the legacy MATLAB workflow
+- For other `Nc` values, the simulation uses fresh random draws each run -->
+- *`Nc = 4` implies a 4x4 tissue
+- `Nc>=10` can take many hours to run, so start smaller when testing

sopsim-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sopsim"
+version = "0.2.0"
+description = "SOPSim simulation library"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    {name = "Olaolu Olugbenle"},
+    {name = "Dr. William Annan"}
+]
+
+dependencies = [
+    "numpy",
+    "scipy",
+    "tqdm",
+    "shapely",
+    "matplotlib",
+    "fastapi",
+    "uvicorn[standard]",
+    "pydantic",
+    "python-dotenv",
+]
+
+[tool.setuptools]
+packages = ["sopsim", "sopsim.web_dist"]
+include-package-data = true
+
+[tool.setuptools.package-data]
+sopsim = ["mat_files/*.mat", "web_dist/index.html", "web_dist/assets/*"]
+
+[project.scripts]
+sopsim = "sopsim.cli:main"

sopsim-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sopsim-0.2.0/sopsim/__init__.py

@@ -0,0 +1,5 @@
+"""SOPSim package."""
+from .core import sopsim
+
+__all__ = ["sopsim"]
+__version__ = "0.1.0"

sopsim-0.2.0/sopsim/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+
+raise SystemExit(main())

sopsim-0.2.0/sopsim/artifacts.py

@@ -0,0 +1,79 @@
+"""Utilities for writing local SOPSim outputs."""
+from __future__ import annotations
+
+import json
+import pathlib
+from typing import Any, Dict
+
+import numpy as np
+
+from .run_sopsim import generate_plots
+
+
+def _jsonable(value: Any) -> Any:
+    if isinstance(value, np.ndarray):
+        return value.tolist()
+    if isinstance(value, (np.integer, np.floating)):
+        return value.item()
+    if isinstance(value, dict):
+        return {key: _jsonable(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(item) for item in value]
+    return value
+
+
+def write_metadata(out_dir: pathlib.Path, inputs: Dict[str, Any], FData, extra: Dict[str, Any] | None = None) -> dict:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    metadata = {
+        "inputs": _jsonable(inputs),
+        "FData": _jsonable(FData),
+        "summary": {
+            "FinalTime": float(FData[0]),
+            "RSA": float(FData[1]),
+            "mean_LSA": float(FData[2]),
+        },
+    }
+    if extra:
+        metadata.update(_jsonable(extra))
+
+    (out_dir / "metadata.json").write_text(json.dumps(metadata, indent=2))
+    return metadata
+
+
+def save_simulation_outputs(
+    out_dir: pathlib.Path,
+    inputs: Dict[str, Any],
+    FData,
+    LSA,
+    MeanDin,
+    Notch_time_step,
+    MeanSOPNotch,
+    MeanEPNotch,
+    FinalNotch,
+    ContP,
+    *,
+    generate_figures: bool = True,
+) -> dict:
+    """Persist the standard output bundle for a completed simulation."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    if generate_figures:
+        generate_plots(
+            inputs["Nc"],
+            inputs["r"],
+            ContP,
+            MeanDin,
+            Notch_time_step,
+            MeanSOPNotch,
+            MeanEPNotch,
+            FinalNotch,
+            LSA,
+            out_dir,
+        )
+    return write_metadata(
+        out_dir,
+        inputs,
+        FData,
+        extra={
+            "result_files": sorted(path.name for path in out_dir.iterdir() if path.is_file()),
+        },
+    )

sopsim-0.2.0/sopsim/cli.py

@@ -0,0 +1,157 @@
+"""Command line entry point for SOPSim."""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+from typing import Sequence
+
+import uvicorn
+
+from .artifacts import save_simulation_outputs
+from .config import (
+    FILOPODIA_LIFE_TIME_VALIDATION_MESSAGE,
+    FILOPODIA_TYPE_VALIDATION_MESSAGE,
+    FILOPODIA_TYPES,
+    MATLAB_REFERENCE_NC,
+    MATLAB_REFERENCE_VALIDATION_MESSAGE,
+    MIN_FILOPODIA_LIFE_TIME,
+    MIN_NC,
+    NC_VALIDATION_MESSAGE,
+    SimulationInputs,
+    build_simulation_parameters,
+)
+from .core import sopsim
+
+DEFAULT_FILOPODIA_TYPE = SimulationInputs().filopodia_type
+DEFAULT_FILOPODIA_LIFE_TIME = SimulationInputs().filopodia_life_time
+
+
+class SOPSimArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:  # pragma: no cover - exercised through CLI behavior
+        self.print_help(sys.stderr)
+        self.exit(2, f"\nError: {message}\n")
+
+
+def positive_int(value: str, *, minimum: int, label: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"{label} must be an integer >= {minimum}.") from exc
+    if parsed < minimum:
+        raise argparse.ArgumentTypeError(f"{label} must be an integer >= {minimum}.")
+    return parsed
+
+
+def run_simulation(args: argparse.Namespace) -> int:
+    inputs = SimulationInputs(
+        Nc=args.nc,
+        filopodia_type=args.filopodia_type,
+        filopodia_life_time=args.filopodia_life_time,
+        use_mat_files=args.use_mat_files,
+    )
+    params = build_simulation_parameters(inputs)
+    result = sopsim(
+        Nc=inputs.Nc,
+        filopodia_type=inputs.filopodia_type,
+        filopodia_life_time=inputs.filopodia_life_time,
+        use_mat_files=inputs.use_mat_files,
+    )
+    out_dir = pathlib.Path(args.out_dir)
+    metadata = save_simulation_outputs(
+        out_dir,
+        params["inputs"],
+        result["FData"],
+        result["LSA"],
+        result["MeanDin"],
+        result["Notch_time_step"],
+        result["MeanSOPNotch"],
+        result["MeanEPNotch"],
+        result["FinalNotch"],
+        params["ContP"],
+        generate_figures=not args.no_plots,
+    )
+
+    print(json.dumps(metadata["summary"], indent=2))
+    print(f"Saved outputs to {out_dir}")
+    return 0
+
+
+def serve_app(args: argparse.Namespace) -> int:
+    uvicorn.run("sopsim.server:app", host=args.host, port=args.port, reload=args.reload)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = SOPSimArgumentParser(
+        prog="sopsim",
+        description="Run SOPSim locally.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Input summary:\n"
+            f"  Nc: integer >= {MIN_NC}. Required input.\n"
+            f"  filopodia_type: one of {', '.join(FILOPODIA_TYPES)}. Default is {DEFAULT_FILOPODIA_TYPE}.\n"
+            f"  filopodia_life_time: integer >= {MIN_FILOPODIA_LIFE_TIME}. Default is {DEFAULT_FILOPODIA_LIFE_TIME}.\n"
+            f"  use_mat_files: only valid when Nc={MATLAB_REFERENCE_NC}\n"
+            "  r: fixed at 1.0\n\n"
+            "Examples:\n"
+            "  sopsim run --nc 4 --filopodia-type A --filopodia-life-time 10 --out-dir output\n"
+            "  sopsim run --nc 4 --use-mat-files --out-dir output\n"
+            "  sopsim serve" #ALT: sopsim serve --host 127.0.0.1 --port 8000
+        ),
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    run_parser = subparsers.add_parser("run", help="Run one simulation and write local outputs.")
+    run_parser.add_argument(
+        "--nc",
+        type=lambda value: positive_int(value, minimum=MIN_NC, label="Nc"),
+        required=True,
+        help=NC_VALIDATION_MESSAGE,
+    )
+    run_parser.add_argument(
+        "--filopodia-type",
+        choices=FILOPODIA_TYPES,
+        default=DEFAULT_FILOPODIA_TYPE,
+        help=f"{FILOPODIA_TYPE_VALIDATION_MESSAGE} (default: {DEFAULT_FILOPODIA_TYPE})",
+    )
+    run_parser.add_argument(
+        "--filopodia-life-time",
+        type=lambda value: positive_int(value, minimum=1, label="filopodia_life_time"),
+        default=DEFAULT_FILOPODIA_LIFE_TIME,
+        help=f"{FILOPODIA_LIFE_TIME_VALIDATION_MESSAGE} (default: {DEFAULT_FILOPODIA_LIFE_TIME})",
+    )
+    run_parser.add_argument(
+        "--out-dir",
+        type=pathlib.Path,
+        default=pathlib.Path("output"),
+        help="Directory for plots and metadata",
+    )
+    run_parser.add_argument("--no-plots", action="store_true", help="Skip generating figure files")
+    run_parser.add_argument(
+        "--use-mat-files",
+        action="store_true",
+        help=MATLAB_REFERENCE_VALIDATION_MESSAGE,
+    )
+    run_parser.set_defaults(func=run_simulation)
+
+    serve_parser = subparsers.add_parser("serve", help="Start SOPSim as a website, local to your computer.")
+    serve_parser.add_argument("--host", default="127.0.0.1", help="Host interface to bind")
+    serve_parser.add_argument("--port", type=int, default=8000, help="Port to bind")
+    serve_parser.add_argument("--reload", action="store_true", help="Enable uvicorn reload mode")
+    serve_parser.set_defaults(func=serve_app)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+        if not hasattr(args, "func"):
+            parser.print_help()
+            return 0
+        return int(args.func(args))
+    except ValueError as exc:
+        parser.error(str(exc))