Feature request: support for `tfun` (inline tabulated functions)

[wshlavacek]

Feature request: support for tfun (inline tabulated functions)

Summary

PyBioNetGen 0.8.6 bundles a version of BNG2.pl that does not recognize tfun syntax in begin functions blocks. The BioNetGen Perl engine in the development repo already supports tfun (inline tabulated data functions), but this support has not yet made it into the BNG distribution bundled with PyBioNetGen.

Reproducer

begin model
begin parameters
end parameters
begin molecule types
  X()
end molecule types
begin seed species
  X() 0
end seed species
begin observables
  Molecules Xtot X()
end observables
begin functions
  f() = tfun([0, 1, 2, 3], [0, 10, 20, 30], time)
end functions
begin reaction rules
  0 -> X() f()
end reaction rules
end model

generate_network({overwrite=>1})
simulate({method=>"ode", t_end=>3, n_steps=>30})

Running with bionetgen run:

ABORT: Expecting operator argument in tfun([0, 1, 2, 3], [0, 10, 20, 30], time)
  at [0, 1, 2, 3], [0, 10, 20, 30], time)

Running the same file with perl /path/to/bionetgen/bng2/BNG2.pl from the development repo succeeds (reads 1 function, simulates correctly).

Environment

• PyBioNetGen: 0.8.6 (pip)
• Bundled BNG: 2.9.3 (site-packages/bionetgen/bng-mac/)
• Platform: macOS (Darwin 24.6.0)

Context

tfun enables inline tabulated data functions with linear or step interpolation, indexed by time, a parameter, or an observable:

f() = tfun([x0, x1, ...], [y0, y1, ...], index_var)
f() = tfun([x0, x1, ...], [y0, y1, ...], index_var, method=>"step")

This is useful for embedding experimental data directly in BNGL model files for comparison with simulation output (e.g., in parameter_scan actions).

The development BNG repo includes tfun parsing and evaluation in both BNG2.pl and run_network. The Validate directory contains several test_tfun_*.bngl files exercising the feature. Updating the BNG distribution bundled with PyBioNetGen to include these changes would resolve the issue.

Workaround

Setting BNGPATH to a local clone of the development repo before invoking bionetgen run:

export BNGPATH=/path/to/bionetgen/bng2
bionetgen run -i model.bngl -o outdir

[wshlavacek]

Correction to the workaround: The BNGPATH environment variable workaround listed above does not actually work with bionetgen run. PyBioNetGen hardcodes the bundled BNG path in core/defaults.py and does not check BNGPATH. The BNGPATH env var is only used internally by the Perl BNG2.pl script to locate its own modules — it has no effect on which BNG2.pl PyBioNetGen invokes.

Working workaround: Symlink the bundled BNG directory to a local clone of the development repo:

# Back up the bundled BNG
mv /path/to/site-packages/bionetgen/bng-mac /path/to/site-packages/bionetgen/bng-mac.bak

# Symlink to dev repo
ln -s /path/to/bionetgen/bng2 /path/to/site-packages/bionetgen/bng-mac

(Replace bng-mac with bng-linux or bng-win on other platforms.)

Note: The development repo's run_network binary must also be rebuilt from source for parameter-indexed tfun to work correctly — there is a bug where init_network() resets the has_tfuns flag after parsing. A fix has been submitted: RuleWorld/bionetgen#291