Skip to content

Optional BNGsim integration: in-process simulation + multi-format input#102

Draft
wshlavacek wants to merge 2 commits into
RuleWorld:mainfrom
wshlavacek:pr66-bngsim-integration
Draft

Optional BNGsim integration: in-process simulation + multi-format input#102
wshlavacek wants to merge 2 commits into
RuleWorld:mainfrom
wshlavacek:pr66-bngsim-integration

Conversation

@wshlavacek
Copy link
Copy Markdown
Contributor

@wshlavacek wshlavacek commented May 27, 2026

Summary

Adds BNGsim as an optional in-process simulation engine for PyBioNetGen.
The integration is a pure soft-import: if bngsim is not installed, every
simulation routes through the existing subprocess BNG2.pl / run_network / NFsim
path exactly as today. With bngsim absent, behavior is unchanged — the
contract this PR is built around.

bngsim is never an install dependency. It is offered as an optional extra
(pip install bionetgen[bngsim], floor bngsim>=0.9.10) and gated at runtime
by a single BNGSIM_AVAILABLE flag; a BIONETGEN_NO_BNGSIM=1 kill-switch and a
version floor (MINIMUM_BNGSIM_VERSION = 0.9.10) force the legacy path when set
or when an older bngsim is present.

New capabilities (only active when bngsim is installed)

  • In-process ODE, SSA, and NFsim simulation via bngsim (no Perl subprocess
    for the simulation step).
  • Multi-format input with auto-detection — .bngl, .net, SBML (.xml),
    and Antimony (.ant) — plus an explicit override (--format / format=).
  • tfun (inline tabulated functions): models using tfun(...) run correctly
    in-process (the bridge routes them to the interpreted RHS, since bngsim
    codegen + tfun is not yet stable).
  • Codegen (compiled C RHS) for accelerated ODE simulation, with automatic
    fallback to the interpreted RHS where codegen is unsafe.
  • Threaded parameter scanning and steady-state solving, with an optional
    persistent helper process to amortize bngsim import cost across scan points.
  • New CLI flags on run: --method, --format, --timeout, --no-bngsim.
  • New bionetgen.run(...) kwargs: simulator= (default "auto"), method=,
    format=, t_span=, n_points=, timeout=.

Issues addressed

Closes #66 — BNGsim integration: in-process simulation + multi-format support.
Closes #65tfun (inline tabulated functions) now run in-process.

Addresses #6 — input-format auto-detection removes the hard file-extension
requirement (with an explicit --format/format= hint).
Addresses #22 — the in-process engine removes Perl from the simulation step
(a different mechanism than the py-perl5 suggestion, but the same goal); left
open for the remaining broader work.

Scope of the diff

Purely additive against upstream/main — 20 files, +7976/−53 (the deletions are
re-routings inside three existing entry points, not feature removals):

  • 3 new modules: core/tools/bngsim_bridge.py (the soft-import + routing
    core), core/tools/bngsim_backend_helper.py, core/tools/bngsim_parameter_scan.py.
  • 3 pure-additive touchpoints: __init__.py (+3, export BNGSIM_AVAILABLE),
    core/tools/__init__.py (+13), core/tools/info.py (+16, banner line).
  • 3 routing touchpoints (route through the bridge iff available, else legacy):
    main.py (the new CLI flags), core/tools/cli.py, modelapi/runner.py.
  • Packaging: setup.py (+9) — adds only extras_require={"bngsim": [...]};
    bngsim stays out of install_requires.
  • Tests: tests/conftest.py (+34, require_bng2/require_atomizer fixtures)
    and 9 new tests/test_bngsim_*.py files.

Test plan / verification

  • With bngsim 0.9.10 installed: 248 bngsim tests pass; a model runs through
    the in-process path and produces output.
  • With bngsim genuinely uninstalled: the bngsim test files give
    239 passed / 9 skipped / 0 errors (the 9 skips are the real-engine paths,
    guarded by skipif(not BNGSIM_AVAILABLE)); no collection-time import bngsim.
  • Legacy-path equivalence: test_model_running_CLI is identical on this branch
    with bngsim disabled vs. pristine upstream/main (same pre-existing results) —
    i.e. zero regression on the no-bngsim path.
  • black --check clean on all added/changed files; Python 3.8–3.12 safe.

Trying the optional engine (not required to use this PR)

bngsim is a compiled extension and is not on PyPI yet, so pip install bionetgen[bngsim] will not resolve until it is published. To try the in-process
engine now, install a prebuilt wheel from the release:

CI does not install bngsim, so none of this affects the green-checks contract.

Optional in-process simulation backend, used iff `import bngsim` succeeds;
otherwise the existing BNG2.pl / run_network / NFsim path is used unchanged,
so behavior is identical when bngsim is absent. bngsim is never an install
dependency (pure soft-import).

Adds the bridge module, the BNG2.pl backend-hook helper, the in-process
parameter_scan driver, CLI/runner routing (auto / --no-bngsim), version
reporting, and tests. Touchpoints are additive; the non-bngsim path is
left byte-for-byte upstream.

Toward RuleWorld#66.
Packaging (B3): add extras_require={"bngsim": ["bngsim>=0.9.10"]} so the
optional in-process engine is discoverable via `pip install bionetgen[bngsim]`,
while keeping bngsim out of install_requires (never a hard dependency). The
extra's floor matches MINIMUM_BNGSIM_VERSION in the bridge.

Bridge: bump MINIMUM_BNGSIM_VERSION 0.6.0 -> 0.9.10. 0.9.0 settled the
method-independent gdat/scan output schema (bngsim RuleWorld#58) the parity differ
normalizes against; 0.9.10 is the current validated release. Refresh the
floor-rationale comment, which still cited the stale 0.6.0/RuleWorld#40 reason.
Update the version-guard test's minimum-version case to 0.9.10.

With bngsim absent the bridge soft-imports to the legacy subprocess path
unchanged; the bngsim test files skip/pass cleanly (239 passed, 9 skipped,
0 errors with bngsim genuinely uninstalled).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

BNGsim integration: in-process simulation, multi-format support, Python 3.12 fixes Feature request: support for tfun (inline tabulated functions)

1 participant