Release Notes

From BioNetWiki

(starting with version 2.0.34)

Contents 1 version 2.1.8 testing 1.1 New features 1.2 Development features 1.3 Core BioNetGen updates and bug fixes 1.4 Network2 simulator updates and bug fixes 1.5 Network3 development release 1.6 NFsim compatibility 1.7 et Cetera 1.8 Known Issues 1.9 Revision Notes 1.9.1 revision 597 1.9.2 revision 549 2 version 2.1.7 3 version 2.1.6 4 version 2.1.5 5 version 2.1.4 6 version 2.1.3 7 version 2.1.2 8 version 2.1.1 9 version 2.1.0 10 version 2.0.48 11 version 2.0.46 12 Distributions prior to 2.0.46 12.1 2.0.45 12.2 2.0.44 12.3 2.0.41 12.4 2.0.40 12.5 2.0.39 12.6 2.0.38 12.7 2.0.37 12.8 2.0.36 12.9 2.0.35 12.10 2.0.34

version 2.1.8 testing

This release appears to be stable, but is still considered a beta release. We welcome feedback and bug reports. Thanks.

New features

• Trajectory continuation: Extended simulation results may be appended to a previous output file by passing the argument continue=>1 to simulate_ode() or simulate_ssa(). If the argument t_start appears in conjunction with continue, then the value of t_start must equal t_end from the previous simulation. The continue feature is useful for generating trajectories from multi-stage simulations.
• New species statistics for on-the-fly simulations with Network2: An auxilliary output file named [model_prefix].jdat contains 4 data fields: time, number of populated species, number of species that have been populated at some point in the current simulation, and number of species in the current network (including edge species). Auxillary output is enabled by pasing the argument print_n_active_species=>1 to simulate_ssa().
• Molecule type checking for observable declarations: BNG will produce an error at parse time if observable patterns contain molecules, components or states not defined in the molecule types block (if defined).
• Updated rule parsing method detects component state changes from a wildcard in the reactant to a specific state in the product. Previous versions of BNG ignored state changes when a wildcard appeared in the reactant side.
• Network3, a new simulator with support for functional ratelaws ( see section below).

Development features

• Local function expansion for network models: Local functions are evaluated for each reaction instance created during network generation. The resulting network model can be simulated in Network3 (see section on Network3 below), which supports function ratelaws. Simulation results are equivalent to NFsim. LIMITATIONS: molecule tags are not currently supported in local function evaluations. This feature may appear in a future release if there is sufficient demand. (see NFsim documentation for more info on local functions.)
• Symmetry corrections for Molecule observables: This release implements methods that correct molecule observable counts with respect to symmetry. For example, the observable A(b,b) overcounts matches by a factor of two. This feature is especially useful when higher order symmetries confuse the interpretation of observable counts. UPDATE: To preserve backward compatibility, symmetry corrections are disabled in this version. A future version will include a option for symmetry correction. If there is demand for this feature, implementation will be given high priority.
• New action: generate_hybrid_model(). This action partially expands a reaction network around a set of population species specified in the optional blocks population types and population maps. This feature is creates a transformed BNGL model that may be simulated using a hybrid particle-population method in NFsim. This is useful for combintorially complex model that contain a few species with high populations. See full documentation for details.
• New blocks: population types and population maps. See action generate_hybrid_model().
• New molecule types attribute: PopulationType. This attribute flags a molecule as a population type. NOTE: population type molecules may not contain components. NFsim recognizes this attribute and treats the molecule as a population variable. See action generate_hybrid_model().

Core BioNetGen updates and bug fixes

• Updated writeMfile(): M-file code generation was updated to provide interface compatibility with writeMexfile(). The code generated by either method can be substituted in any MATLAB routine without modifying the input or output arguments. See complete notes on Mex code generation.
• Use of special ratelaw Sat with more than R+1 arguments, where R is the number of reactants, will produce an informative error at parse time.
• Use of special ratelaw MM with non-bimolecular or symmetric reaction rules will produce an informative error at parse time.
• Use of special ratelaw MM with fewer or more than 2 arguments will produce an informative error at parse time.
• Fixed parsing bug that caused an infinite loop when a “.” appeared in a list of components.
• Patterns and species with duplicated bond labels will produce an informative error at parse time.
• Minor changes to whitespace formatting in NET and BNGL file outputs. This may affect downstream processing if parses are not robust with respect to whitespace. NOTE1: spaces, multiple spaces and tabs should all be treated identically. Continuing a BNGL line past a newline character requires a "\". Whitespace at the beginning or end of a line is ignored. Whitespace should not appear within a pattern or species. NOTE2: These changes caused trouble in the RuleBender parser, so some of these changes were rolled back.
• Minor changes to reaction rule processing: Remove bond transformations are ignored if one or both molecules participting in the bond are deleted by other transformations. NOTE: this saves a little effort when firing reactions in NFsim. This also simplified NFsim logic by avoiding situations where a bond removal was attempted on a deleted molecule.
• Internal code restructuring: Improved modularity of reaction rule application. Created copy constructor methods for all classes.
• Improved function parser in BNG: functions now have a private namespace so that argument names do not conflict with global parameter names. This permits arbitrary nesting of functions (although cyclical dependencies are forbidden).

Network2 simulator updates and bug fixes

• Fixed bug that potentially led to observable count errors in Network2 on-the-fly simulation. BNG added edge species to observables immediately, while Network2 assumed observables were updated only after species were populated. This led to errors in some cases. NOTE: this bug was not present in any numbered releases, but did appear in a distribution packaged with NFsim. This bug had no effect on the accuracy of simulations performed with NFsim.
• Fixed handling of higher-order reaction symmetries in Network2. Previously, only bimolecular symmetry was handled correctly.
• Fixed bug in Network2 implementation of SSA where fixed species (constant population) were handled incorrectly. In the typical case, fixed species were permitted to vary. In rare cases this resulted in fixing species that should be permitted to vary. NOTE: this bug did not affect ODE simulations or NFsim.
• Fixed bug in Network2 where reactions with zero products caused the simulation to fail before start. NOTE: reactions with zero products occur when one the products are flagged as fixed species either globally or with respect to the reaction.
• Changes to Network2 output formats: CDAT file now has 12 digit precision for time and species. GDAT file has 8 digit precision for time and observables. NOTE: prior versions had 16 digit precision in the CDAT file, this resulted in fluctuation of the least significant digit due to numerical precision limits. While the fluctations were numerically insignificant, this caused problems in post processing scripts that compared values without a tolerance bound.
• Changes to special ratelaws Sat, MM and Hill: Network2 calculates discrete corrections to reaction propensities due to symmetric reactants. NOTE: prior versions allowed symmetric reactions to fire when only one copy of the reactant was present in the system.
• Added libmathutils.a to the makefile clean script.

Network3 development release

• Network3 is a development version of the BioNetGen Network Simulator. Network3 supports global function ratelaws. Global function ratelaws define the elementary rate constants in terms of constant parameters and global observables. NOTE: Network2 is still the default network simulation in this release. The user must compile Network3 by entering the Network3 subdirectory and executing make. LIMITATIONS: Argument passing is not yet supported. On-the-fly network generation is broken.

NFsim compatibility

• Added optional TotalRate keyword for rate laws. TotalRate instructs NFsim to treat a global function as the overall reaction rate, rather than the usual interpretation as per reactant set. Network simulations do not support this syntax.
• Symmetry factor calculation: A symmetry factor based on reaction center symmetries is calculated while processing each reaction rule. The symmetry factor is written to XML with id “symmetry_factor”. In the future, this will permit full compatibility between NFsim and Network simulations with respect to complex symmetries.

et Cetera

• New example model in Models2 subdirectory: Trivalent Ligand--Bivalent Receptor (TLBR).
• Improved collection of validation models: Validation models help us indentify bugs earlyin the development process. Improved validation will increase the reliability of BioNetGen releases.
• Organized third party libraries in [BNG_root]/libsource directory.
• Updated Makefile: Compile Network3 by calling “make network3” from the BNG root directory. Gets third party libraries from libsource directory, rather than an internal subdirectory.

Known Issues

• Network3 simulator does not support true function arguments.
• On-the-fly network generation is not supported in Network3 (please use Network2).
• Infinite loop encountered in Makefile if "clean" recipe is executed while subdirectories are missing (ctrl-c will terminate the loop).

Revision Notes

revision 597

• fixed bug that caused a fatal error when setParameter action is called with an unquoted parameter name.
• fixed bug that, under certain conditions, resulted in failure to update .net file prior to simulation.

revision 549

• BUG NOTICE (fixed in 597): a fatal error is produced if the setParameter action is called with an unquoted parameter name. This error can be avoided by adding quotes to the parameter name. The parameter scanning script 'scan_var.pl' is affected by this bug. A quick fix is possible by commenting out the "use strict" pragma in Perl2/BNGModel.pm.
• BUG NOTICE (fixed in rev597): under certain conditions the .net file is not updated prior to simulation. This occurs when an old .net file already exists with the same name and the UpdateNet flag is false. Deleting the old NET file will resolve the issue.
  • The main BioNetGen executable script 'BNG2.pl' has been relocated to the root directory. This may cause temporary incompatibility with RuleBender.
• Output files are now written to the current working directory by default. Previously the default path was the directory containing the model. The default path may be changed by calling BNG2.pl with the argument '-outdir PATH'. Alternatively, passing the 'prefix' option to BNG actions will override default path and filename prefix.
• Fixed a bug in writeSBML() that caused failure when writing derived parameters.
• Fixed bug in Network3 simulator that caused failure of some SSA simulations with functional ratelaws.
• Fixed a bug in handling rate multiplicities of symmetric reactions with multiple component tags (uncommon).
• Minor improvements to output actions writeMfile() and writeMexfile() with regards to MATLAB plot asthetics and filename handling.
• New test feature: BNGconsole. Execute 'BNG2.pl -console' to start a simple interactive console. This is a sandbox feature and is not yet fully developed.
• Thanks to extensive user feedback, we have greatly expanded our set of validation models. This should improve reliability of future releases.

version 2.1.7

• Fixed Bug from v2.1.6 related to molecule and species deletion.
• New model simulation feature: writeMEXfile().
  • Simulate ODE network models from the MATLAB interpreter through the MEX interface.
  • Compilation depends on Sundials CVODE library and the MATLAB MEX compiler.
  • Very fast.
  • Supports global functions.
  • Useful for post-simulation analysis in MATLAB.
  • This feature is in beta testing! Your feedback is appreciated.

version 2.1.6

• This version has a serious bug related to molecule and species deletion. Upgrade to 2.1.7 is highly recommended. Results generated should be re-checked and verified if the model contains any deletion rules.
• Successfully translates a given BioNetGen model to SSC model.
  • The translator does not handle rules with more than two reactants. However, it can handle any number of operations on the reactants.
  • Rules containing non-equivalent SSC features like, '?', exclude_reactants, include_reactants, exclude_products or include_products, MatchOnce, labels '%' and Compartments will be omitted and commented in the translated file. A warning will also be generated specifying that rule.
  • SSC cannot use patterns where connectivity is not specified.
  • As SSC does not handle molecules with same component names, the translator translates the rule but does not provide any combinatorial expansion of the rule. And thus, when compiling, SSC will complain about the rule with molecule with same component name.

version 2.1.5

• Implements all compartmental features described in the Winter Simulation Conference paper.
  • location of synthesized molecules is inferred, if not specified explicitly.
  • species location context in binding/unbinding rules is now permitted.
• Binaries are not compiled: after opening the archive file, type "make" in the root directory.
• Some output formats supported for compartments: BNGL, Matlab M-file, and XML. (Note that rule models, but not reaction networks, are supported in XML. This is true for compartmental and non-compartmental models.) SBML is not currently supported for compartmental models.
• Saturation, Michaelis-Menten, and Hill-type rate laws are implemented for non-compartmental models, but these rate laws will not work correctly in a compartmental model (fix coming soon).
• Older versions of Motivating_example_cBNGL.bngl have a slight incompatibility (please download the latest version here): abstract molecules used as sinks or sources must have a compartment location, even if it is irrelevant.
• If reactant patterns in a rule have partial overlap, the symmetry factor for reaction rates may be calculated incorrectly. E.g. R(a) + R(a,b~pY) -> R(a!1).R(a!1,b~pY) will be handled incorrectly when the first reactant also matches the second pattern. This is a legacy issue--the problem exists in all previous versions. This type of rule is not very common, so most models are unaffected.

version 2.1.4

• Fixed bug in symmetry handling in synthesis reactions.
• Some improvements to the NFsim interface (NFsim is not yet included in the public distributions).

version 2.1.3

• Added Hill rate law (usage is Hill(k,K,n), which gives a rate of k*x1^n/(K^n+x1^n)). This rate law works only with simulate_ode and simulate_ssa, and not with NFsim, Matlab, or XML output. Here is an example file the demonstrates use of the Hill function.

version 2.1.2

• Fixed non-elementary rate laws.

version 2.1.1

• Bug notice: Non-elementary rate laws are broken in this version. This bug is fixed in the next release (2.1.2). Support for these rate law types is considered legacy and users are encouraged to switch to using Function notation, which will be introduced at the time NFsim is released.

version 2.1.0

• Implements compartmental BNGL (cBNGL), see Wsc09.
• -log option to BNG2.pl automatically generates log file without redirect.
• Improved Matlab output.
• Outputs XML format that is compatible with NFsim and GetBonNie.
• Resolves reaction center and context to alleviate symmetry issues (some issues remain - multiple ways to satisfy rule context no longer multiples the reaction rate, but symmetries in rule context are not counted correctly).
• Doesn't include binaries, which have to be made from source (type 'make' in the root directory of the distribution).
• Default compartment location for molecule synthesis not yet implemented. At present, all synthesized molecules must have an explicit compartment location included in the product side of the rule.
• SBML output does not support compartments.
• The "$" operator and a species location prefix "@C:" cannot be used together on a reactant or product in a rule.
• Bug notice: This version does not correctly handle symmetry in the context of a rule that is not broken by application of the rule, as in the example

R(l)+L(r,r,r) -> R(l!1).L(r!1,r,r) kp1, km1. The correct multiplicity of this reaction is 3 (if R is monovalent), but BNG 2.1.0 gives the reaction a multiplicity of 3/2. This problem is fixed in version 2.1.1. For now, the fix is to manually correct the multiplicity by adding multiplicative factors in the rate law. For the example above, the correct rate constants would be 2*kp1 and 2*km1.

version 2.0.48

• run_network executable under Mac OS X is not optimized for performance on Intel processors. Recompile by typing 'make' in distribution directory.

version 2.0.46

• run_network executable under Mac OS X is not optimized for performance on Intel processors. Recompile by typing 'make' in distribution directory.
• Stable version that allows component state mapping but retains checks for incomplete molecule specifications.

--Faeder 00:16, 6 July 2007 (MDT)

Distributions prior to 2.0.46

2.0.45

• This is an ALPHA release. It provides a temporary fix for an issue that prevents use of rules that map component states from reactant onto product molecules, which are required for metabolic label tracing.

--Faeder 09:28, 6 June 2007 (MDT)

2.0.44

• Optional syntax changes
  • Enclose model block in begin/end model
  • Omit rate constants in reaction rules – automatically generated.
  • Use arbitrary math expressions for initial concentrations and rate constants (not rate laws).
• Define observables based on stoichiometry of a single component.
• Ability to use HNauty for graph isomorphism checking using setOption command.

--Faeder 09:55, 28 March 2007 (MDT)

2.0.41

• Improved recognition of OS specific binaries using the $Config{myarch} variable in Perl.
• Fixed model naming in SBML files (path header is removed).

--Faeder 10:36, 8 November 2006 (MST)

2.0.40

• Now includes RuleBuilder GUI interface to BioNetGen.
• Back end executables for Linux, Mac, and Windows also provided in the default distribution.

2.0.39

• Fixes small bugs in reading of Expressions from parameter block.

2.0.38

• Fixes bug that appeared starting in 2.0.36 that reading of Reactions from a .NET file was broken. It also marks the first version to use the new Expression.pm module, which allows the use of simple math expressions in the parameter block. This version may be somewhat unstable due to incomplete testing of the Expression.pm and other related changes. --Faeder 21:31, 27 September 2006 (MDT)

2.0.37

• Fixes deleteMolecules bug. Also introduces stricter Molecule Type checking. If the Molecule types block is used, only molecules matching defined types will be allowed as seed species, in observables, or in reaction rules. You will also note that Compartments are now defined in the .net file. There is now a partial implementation of Compartments, but the next release will fully implement these capabilities, and will be accompanied by documentation of the new syntax.

--Faeder 11:13, 13 September 2006 (MDT)

2.0.36

• Fixes Sat/MM bug involving reactions that use MM and Sat RateLaws in which reactant order was not preserved in the generated reactions.

2.0.35

• Fixed the Dimer dissociation bug, which resulted from improper checking of product connectivity when molecules were deleted in a reaction. The bug could only arise in a rule in which a molecule is deleted, but it is otherwise difficult to anticipate. Updating to this version is therefore strongly recommended.

--Faeder 00:53, 27 July 2006 (MDT)

2.0.34

• Fixed bug in handling of include/exclude directives that allowed reactions that should have been excluded. A test input file that demonstrates the bug is here.
• Added a java plotting utility called PhiBPlot for plotting CDAT and GDAT files.

--Faeder 12:11, 11 July 2006 (MDT)