The table-function guide says BioNetGen writes a tfun into the .net, but the released BioNetGen 2.9.3 aborts on every tfun(...) spelling: Model.from_bngl raises 'Expecting operator argument', and nothing says a newer BioNetGen is needed

Open Beginner friendly
  • Is something wrong?
#1,674 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
77/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
documentation

Research direction

Start with docs/user-guide/table-functions.md and loading-models.md, which the issue identifies as giving incomplete BioNetGen guidance. Clarify that BioNetGen 2.9.3 rejects tfun(...) in BNGL and explain the supported .net or Python API route; the issue suggests noting that BNGL use needs a newer BioNetGen. Done when both guides clearly state the version limitation and working alternatives.

Written by the indexing model from the issue text.

Description

documentation

docs/user-guide/table-functions.md reads as though BioNetGen writes a tfun() into the .net it generates. The released BioNetGen, 2.9.3, does not accept tfun(...) in a BNGL functions block at all. That is the BioNetGen the docs point to: loading-models.md names BNGPATH=/path/to/BioNetGen-2.9.3, and the bngl extra brings PyBioNetGen, which bundles 2.9.3. A user who declares a table function in BNGL with those tools gets a ModelError from Model.from_bngl. The failure is loud, and no number is wrong. What is missing is a sentence saying which BioNetGen is needed.

Found while checking a lead of #1532 (the one filed as #1657). Reproduced on bngsim 0.17.1 (the PyPI wheel, macOS arm64, Python 3.12) with BioNetGen 2.9.3.

What the guide says

  • "The index may also be written as a call, A_tot() or time(), as BioNetGen writes it into the .net when the model does; it names the same thing."
  • "... so one .tfun file works across the spellings BNG accepts. This matches BioNetGen's TfunReader.pm." Release 2.9.3 has no Perl2/TfunReader.pm.

The guide also gives the route that does work with the released tools: "In a .net file, it is parsed automatically", and "No change to BNG2.pl is required, so tfun() can be added to a .net file by hand or built through the Python API." It never shows a tfun in BNGL, and it never says that the released BioNetGen rejects one.

Repro (python repro.py; needs BNGPATH pointing at BioNetGen 2.9.3)

"""A tfun in a BNGL functions block, loaded with the released BioNetGen 2.9.3. Needs BNGPATH."""
import os
import tempfile

import bngsim

BNGL = """begin model
begin molecule types
  A()
end molecule types
begin seed species
  A() 0
end seed species
begin functions
  F() = tfun([0,10,12,50],[0,5,0,0], time, method=>"step")
end functions
begin reaction rules
  0 -> A() F()
end reaction rules
end model
"""
path = os.path.join(tempfile.mkdtemp(), "m.bngl")
with open(path, "w") as fh:
    fh.write(BNGL)
try:
    bngsim.Model.from_bngl(path)
    print("loaded")
except Exception as exc:
    lines = str(exc).splitlines()
    print(type(exc).__name__ + ":", lines[0])
    print("\n".join(line for line in lines if "ABORT" in line or "BioNetGen version" in line))

ModelError: BNG2.pl generated no network from m.bngl (exit 1). BNG2.pl said:
BioNetGen version 2.9.3
ABORT: Expecting operator argument in tfun([0,10,12,50],[0,5,0,0], time, method=>"step") at [0,10,12,50],[0,5,0,0], time, method=>"step")

In the check, the release aborted in the same way on each spelling the guide lists: inline data or a file, indexed by time, a parameter, an observable or a function. Its own older spelling, TFUN(Atot, 'dose.tfun'), aborts with "TFUN functions are not supported for non-NFsim simulators." A development BioNetGen accepted every file and wrote the tfun line into the .net. It prints the same version string, "BioNetGen version 2.9.3", so a user cannot tell the two apart by version.

What might be done

It may be best to say, near the top of the guide and in loading-models.md, that a tfun in BNGL needs a BioNetGen newer than release 2.9.3, and that with the released BioNetGen a table function is added to the .net by hand or through Model.add_table_function. Perhaps Model.from_bngl could also add a line to its error when BNG2.pl's abort names tfun(.

Not covered by

No open or closed issue. #709's body notes in passing that BNG2.pl 2.9.3 cannot parse tfun(...).

Dominant language
Python
Stars
3
Forks
5
Avg merge
1d 1h
Merged PRs (30d)
361

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from lanl/bngsim

All issues in lanl/bngsim

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.