0.5.2

A few additional extensions. Mainly:

• FnUpdate now implements Display using default variable/parameter names (you should still use FnUpdate::to_string if you want the actual context-aware names).
• SymbolicContext now has network-parameter "introspection", i.e. network_parameters iterator, find_network_parameter search, and get_network_parameter_arity/get_network_parameter_name.

0.5.1

This is a minor extension of the 0.5.0 release in which we add:

• SymbolicContext::as_canonical_context function (creates a new context without extra variables).
• Reachability API object with a new "structural" reachability algorithms.
• FunctionTable::contains function.

0.5.0

Well, this is a big one... We are adding several new major features:

Highlights

• We now support arbitrary expressions as arguments to uninterpreted function calls. For example, f(g(a,b), c | d) is now a valid update function.
• We have significantly reworked the mechanism behind inline_inputs and inline_variable to be safer, faster, and hopefully easier to understand.
• We now support symbolic inlining at the level of SymbolicAsyncGraph, i.e. without computing the actual function expression.
• We now support basic Space percolation.
• We can now compute minimal and maximal trap spaces, similar to fixed-point computation (see TrapSpaces API object). We can also represent arbitrary sets of spaces symbolically using NetworkSpaces and NetworkColoredSpaces.

Unfortunately, this required a bunch of breaking changes:

• [breaking contract] Conversion FnUpdate::to_string now produces fewer parentheses around nested & / |. The result is still semantically the same function, but (a & b) & c and a & (b & c) are technically different functions that now resolve to the same string representation (i.e. a & b & c). This helps a lot with readability of DNF/CNF update functions.
• [breaking contract] A variable with no incoming/outgoing regulations can exist in an .aeon file, as long as it has a specified update function (this function can depend on the logical parameters). While this is rather useless in practice, it can be a reasonable result of a network reduction. It is breaking because a previously invalid model can now be valid.
• [breaking contract] In .bnet files, the targets,factors header is now treated as case-insensitive. Again, this only makes previously invalid models valid.
• [breaking API] The signature of FnUpdate::Param changed from (ParameterId, Vec<VariableId>) to (ParameterId, Vec<FnUpdate>). This means the arguments of an uninterpreted function can now be general expressions, not just variables. This required several API changes:
  • FnUpdate::mk_param now accepts &[FnUpdate] instead of &[VariableId]. As an alternative, we provide FnUpdate::mk_basic_param, which is essentially the old function.
  • FnUpdate::as_param now returns &[FnUpdate].
  • FnUpdate::is_specialisation_of removed, as it was never that useful in the first place and became very unclear with the new features.
  • FnUpdate::substitute changed to FnUpdate::rename_all, with more flexible argument types (a map instead of a vector).
  • FnUpdate::eval_in_space removed, as it was also rather useless in the long term.
  • This also changes the signature of several methods in SymbolicContext to use &[FnUpdate] instead of &[VariableId].
• [breaking API] New algorithms for inlining in BooleanNetwork. This changes the signature/semantics of existing methods and adds a few new ones:
  • Added BooleanNetwork::prune_unused_parameters, as it is often required after inlining.
  • BooleanNetwork::infer_valid_graph is now much more robust w.r.t. uninterpreted functions (it can preserve existing constraints and even simplify the update functions a little bit).
  • Changed the signature of BooleanNetwork::inline_inputs. Now it takes two parameters. One determines if the inputs should be detected semantically (instead of syntactically), the other determines if the RG should be repaired after the inlining (e.g. remove unused regulations).
  • Changed the signature of BooleanNetwork::inline_variable. Now it also takes a repair_graph argument which ensured the returned RG is logically consistent. It can also handle uninterpreted functions much better.
  • Added BooleanNetwork::inline_constants, which is similar to BooleanNetwork::inline_inputs, but for constants. It is essentially percolation at the level of the Boolean network.
• [breaking API] Changed internal structure of SymbolicAsyncGraph to allow a graph with no underlying BooleanNetwork to exist. This had some relatively minor but wide-ranging consequences:
  • SymbolicAsyncGraph::new and SymbolicAsyncGraph::with_custom_context now only need a reference to a BooleanNetwork.
  • SymbolicAsyncGraph::as_network now returns Option<&BooleanNetwork>.
  • Changed the way witnesses are generated. Each witness should still use DNF instantiation of an update function, but will now have inferred regulatory graph instead of copying the original BN.
  • Renamed SymbolicAsyncGraph::empty_vertices/mk_empty_vertices to SymbolicAsyncGraph::empty_colored_vertices/mk_empty_colored_vertices. Added actual SymbolicAsyncGraph::empty_vertices/mk_empty_vertices/unit_vertices/mk_unit_vertices methods.
  • Added SymbolicAsyncGraph::new_raw, which allows SymbolicAsyncGraph to be constructed from raw update function BDDs.
  • Added a bunch of utility methods that now provide the most important introspection about the SymbolicAsyncGraph (which was previously done by examining the BooleanNetwork):
    • Added SymbolicAsyncGraph::get_variable_name as well as SymbolicContext::get_network_variable_name.
    • Added SymbolicAsyncGraph::num_vars and SymbolicAsyncGraph::variables as well as SymbolicContext::network_variables.
    • Added SymbolicContext::find_network_variable and SymbolicContext::find_state_variable.
• [breaking API] Removed Space::is_trap_space as it was not correct for general update functions.
• [breaking API] Removed bdd_params and async_graph modules. These have been deprecated for a long time and were incompatible with the new features.
• [breaking API] The bin/dump_graph.rs binary is disabled. Someone can probably re-implement it if we ever need it again.
• [deprecation] GraphVertices::materialize and the IterableVertices struct are now deprecated. You can instead use standard GraphVertices::iter or GraphVertices::into_iter.

Other API changes that are not breaking:

• Added symbolic representation of network spaces using "dual" encodings:
  • Added SymbolicSpaceContext, which implements the actual translation necessary for the encoding (and extends the functionality of a normal SymbolicContext).
  • Added a NetworkSpaces symbolic set, which is analogous to GraphVertices.
  • Added a NetworkColoredSpaces symbolic relation, which is analogous to GraphColoredVertices.
• Added an API object TrapSpaces which implements minimal/maximal/essential trap space search.
• Added OwnedRawSymbolicIterator, which has (roughly) the same features as RawSymbolicIterator, but actually owns the underlying symbolic set and can be thus moved/shared without a lifetime reference.
• Added From<Option<bool>> for ExtendedBoolean.
• Added RegulatoryGraph::variable_names to easily obtain an owned list of variable names.
• Added RegulatoryGraph::add_raw_regulation which can add a regulation using the Regulation object, not strings/IDs.
• Added Space::new_raw which can create a Space object with just variable count.
• Added Space::count_fixed as a counterpart to Space::count_any.
• Added bin/bench_trap_spaces_minimal.rs to test the new trap space feature.
• Added GraphVertices::iter and GraphVertices::into_iter based on raw symbolic projections.
• Added FnUpdate::mk_conjunction and FnUpdate::mk_disjunction that simulate n-ary operators.
• Added FnUpdate::simplify_constants, which eliminates true/false from a function.
• Added RegulationContraint API object which implements RegulationConstraint::mk_observability, RegulationConstraint::mk_activation, and RegulationConstraint::mk_inhibition, as well as RegulationConstraint::infer_sufficient_regulation and RegulationConstraint::fix_regulation. These can be used to repair regulation graphs using BDD analysis. These are not new functions, but a refactoring of old code that can be now made public.
• Added SymbolicContext::mk_instantiated_fn_update which can build a FnUpdate from a BddValuation.
• Added SymbolicAsyncGraph::space_has_var_false and SymbolicAsyncGraph::space_has_var_true as well as SymbolicAsyncGraph::percolate_space. These can be used to implement percolation.
• Added SymbolicAsyncGraph::with_space_context to create an SymbolicAsyncGraph that can be used for space and state exploration at the same time.
• Added SymbolicAsyncGraph::get_symbolic_fn_update to retrieve the "raw" underlying update function.
• Added SymbolicAsyncGraph::inline_symbolic, which can inline a variable at the BDD level, without constructing the underlying network. Also added SymbolicContext::eliminate_network_variable which is required here.
• Fixed a bug in GraphColoredVertices::is_singleton and GraphColoredVertices::pick_singleton which did not account for possible extra variables.

0.4.7

This version introduces a mechanism that can transfer symbolic sets between two "compatible" symbolic domains (i.e. a SymbolicContext or SymbolicAsyncGraph).

The domains are considered "compatible" w.r.t. a particular set if they both admit all symbolic variables that the set depends on (the variables of its "support set"), and if these variables have the same ordering (w.r.t. each other). The exact semantics of this operation depend on how exactly the two networks/domains differ from each other. But as an example, it can be used to "lift" a set of states from a reduced network to the full counterpart. Or it can be used to "restrict" a set of states of the full network down to the reduced network, as long the set only depends on the variables of the reduced network.

API changes:

• Added SymbolicContext::transfer_from(&self, bdd: &Bdd, context: &SymbolicContext).
• Added SymbolicAsyncGraph::transfer_colors_from, SymbolicAsyncGraph::transfer_vertices_from, and SymbolicAsyncGraph::transfer_from.

0.4.6

This version has two relatively minor changes:

• Adds FnUpdate::substitute_variable which replaces every variable occurrence with a provided expression.
• Adds BooleanNetwork::inline_variable which is used to safely eliminate any variable without self-regulation by inlining it into its downstream regulation targets.

0.4.5

This is a small release which:

• Removes a forgotten debug print.
• Adds a better parsing method to FnUpdate.

0.4.4

This version introduces the ability to iterate over projections of symbolic sets. There is one breaking change regarding the way witnesses are generated, but this does not modify the API in any way.

• [bugfix] Added missing mut in ModelAnnotation::get_mut_child.
• Added FnUpdate::build_from_bdd, which can be used to construct DNF update functions from instantiated BDDs obtained through SymbolicContext::instantiate_*.
• The new FnUpdate::build_from_bdd function is now used to generate update functions in witness networks. For small/simple functions, the results should be much more readable (in particular, they don't contain implication, which can be confusing).
• Added symbolic_async_graph::projected_iteration module with the newly introduced iterators. Namely, RawProjection, StateProjection, FnUpdateProjection and MixedProjection. These allow us to interpret any symbolic set through a "view" restricted to state/parameter variables, or a mixture of both.
• Added GraphColoredVertices::state_projection, GraphColoredVertices::fn_update_project, GraphColoredVertices::mixed_projection and GraphColoredVertices::raw_projection. Similar methods have been added to GraphColors and GraphVertices where relevant.
• Added FixedPoints::symbolic_projection which computes a projected result directly (this is faster than computing the full result and then projecting afterwards).

0.4.3

This is again a minor version with enhancements for Biodivine library maintainers. There are only two relevant changes, one of them is potentially breaking, but does not require code changes, only build file update.

• Features supported through z3 are now optional and not enabled by default. Use feature flag solver-z3 to enable them. That is: biodivine-lib-param-bn = { version = ">=0.4.3, <1.0.0", features = ["solver-z3"] }. This change was added to allow compiling lib-param-bn for targets/environments where Z3 is not available. Example of this are standalone binaries that do not use Z3 features and do not wish to depend on Z3. Another example is WASM, where Z3 is theoretically supported, but not in a way that we can use here right now).
• Adds official support for structured annotations in .aeon files. This allows us to add arbitrary key-value annotations with some level of hierarchy that can be safely parsed by lib-param-bn (i.e. avoiding adding new ad hoc rules like we did in the original AEON client). See #40 or the associated tutorial for more info about syntax and capabilities.

0.4.2

This release introduces some new APIs, but they are mainly intended for internal use, hence this is only a minor release.

• You can now (unofficially) use 0/1 instead of false/true constants in logical expressions (applies both to .bnet and .aeon files).
• Now there is support for "extra" BDD variables managed by the SymbolicContext, so that you can create symbolic models "decorated" with additional functionality. Specifically:
  • There is a new constructor SymbolicContext::with_extra_state_variables, which you can use to create a symbolic context with an arbitrary number of extra BDD variables.
  • To access these extra variables, you can use SymbolicContext::all_extra_state_variables, SymbolicContext::extra_state_variables, SymbolicContext::extra_state_variables_by_offset, SymbolicContext::get_extra_state_variable, and SymbolicContext::mk_extra_state_variable_is_true.
  • Just in case you need it, there is now also SymbolicContext::num_state_variables, SymbolicContext::num_parameter_variables, and SymbolicContext::num_extra_state_variables.
  • Similarly, there is a new constructor SymbolicAsyncGraph::with_custom_context that you can use to create a graph with a specific context and "unit" symbolic universe. There are several caveats as to how the SymbolicAsyncGraph can break if you mix the extra symbolic variables into the existing data structures, but as long as you use them outside of the SymbolicAsyncGraph API, you should be fine.
  • There is SymbolicAsyncGraph::existential_extra_variable_projection and SymbolicAsyncGraph::universal_extra_variable_projection which project a symbolic set that uses extra state variables onto a normal set that is guaranteed to be compatible with this symbolic graph.
  • Computation of approx_cardinality and exact_cardinality has been adjusted to account for extra symbolic variables.
  • Finally, there is a new trait called BddSet which now provides default implementations for most common symbolic operations (including the whole Set trait). This removes a lot of redundant code, but some of the old methods are still included to avoid breaking compatibility. Later, we should deprecate them and remove them from the library.

0.4.1

Unfortunately, it turns out that roxmltree version 0.16.0 contains an infinite loop/memory leak and is unusable in some instances. Hence this version downgrades to 0.15.1 for now.