pethgraph-graphml and docs/comments

Cargo.toml

@@ -7,9 +7,10 @@ edition = "2024"
 lalrpop = "0.22"
 
 [dependencies]
-regex = { version = "1.11", features = ["unicode-bool"] }
+regex = { version = "1", features = ["unicode-bool"] }
-lalrpop-util = { version = "0.22", features = ["lexer", "unicode"] }
+lalrpop-util = { version = "*", features = ["lexer", "unicode"] }
-petgraph = { version = "0.8", features = ["serde-1"] }
+petgraph = { version = "*", features = ["serde-1"] }
-# petgraph-graphml = { version = "4" }
+# TODO remove git and use crates.io version when updated
+petgraph-graphml = { git = "https://github.com/jonasbb/petgraph-graphml" }
 serde = { version = "1", features = ["derive", "rc"] }
 serde_cbor_2 = { version = "*" }

src/lib.rs

@@ -1,3 +1,5 @@
+//! Module root
+
 pub mod rsprocess;
 pub mod examples;
 

src/rsprocess/confluence.rs

@@ -1,3 +1,5 @@
+//! Definitions for confluence, strong confluence, loop confluence
+
 use super::perpetual::{
     lollipops_decomposed_named, lollipops_prefix_len_loop_decomposed,
     lollipops_prefix_len_loop_decomposed_named,
@@ -81,7 +83,8 @@ pub fn confluent_named(
 // -----------------------------------------------------------------------------
 
 /// invariant_named checks if all the sets of entities in ```entities``` are
-/// confluent and if so returns the set of all traversed states, together with the loop.
+/// confluent and if so returns the set of all traversed states, together with
+/// the loop.
 /// see invariant
 pub fn invariant_named(
     delta: &RSenvironment,

src/rsprocess/frequency.rs

@@ -1,3 +1,5 @@
+//! Definitions and structure for frequency of elements in a simulation
+
 use crate::rsprocess::perpetual::lollipops_only_loop_decomposed_q;
 use std::collections::HashMap;
 
@@ -7,7 +9,7 @@ use super::transitions::run_separated;
 use super::translator::IdType;
 
 /// structure that holds the frequency of elements of a run or multiple runs,
-/// weighted
+/// weighted.  To print use ```translator::FrequencyDisplay```.
 #[derive(Debug, Clone)]
 pub struct Frequency {
     pub frequency_map: HashMap<IdType, Vec<u32>>,

src/rsprocess/graph.rs

@@ -1,3 +1,5 @@
+//! Definitions for generating graphs from a simulation.
+
 use petgraph::{Graph, Directed};
 use std::collections::HashMap;
 use super::structure::{RSlabel, RSsystem, RSset, RSprocess};
@@ -7,7 +9,7 @@ use std::rc::Rc;
 
 type RSgraph = Graph<RSsystem, RSlabel, Directed, u32>;
 
-/// creates a graph starting from a system as root node
+/// Creates a graph starting from a system as root node
 pub fn digraph(
     system: RSsystem
 ) -> Result<RSgraph, String> {

src/rsprocess/mod.rs

@@ -1,3 +1,5 @@
+//! Crate root
+
 pub mod classical;
 pub mod confluence;
 pub mod frequency;

src/rsprocess/perpetual.rs

@@ -1,8 +1,10 @@
+//! Definitions for finding loops in simulation.
+
 use super::classical::compute_all;
 use super::structure::{RSenvironment, RSprocess, RSreaction, RSset, RSsystem};
 use super::translator::IdType;
 
-/// returns the prefix and the loop from a trace
+/// Returns the prefix and the loop from a trace.
 fn split<'a>(
     set: &'a RSset,
     trace: &'a [RSset]
@@ -11,7 +13,7 @@ fn split<'a>(
     position.map(|pos| trace.split_at(pos))
 }
 
-/// finds the loops by simulating the system
+/// Finds the loops by simulating the system.
 fn find_loop(
     rs: &[RSreaction],
     entities: RSset,
@@ -31,7 +33,7 @@ fn find_loop(
     }
 }
 
-/// finds the loops by simulating the system
+/// Finds the loops by simulating the system.
 fn find_only_loop(
     rs: &[RSreaction],
     entities: RSset,
@@ -51,7 +53,7 @@ fn find_only_loop(
     }
 }
 
-/// finds the loops and the length of the prefix by simulating the system
+/// Finds the loops and the length of the prefix by simulating the system.
 fn find_prefix_len_loop(
     rs: &[RSreaction],
     entities: RSset,
@@ -73,8 +75,8 @@ fn find_prefix_len_loop(
 
 // -----------------------------------------------------------------------------
 
-/// finds only the rules X = pre(Q, rec(X)), but not only x = pre(Q, rec(x))
+/// Finds only the rules X = pre(Q, rec(X)), but not only x = pre(Q, rec(x))
-/// to use in filter_map
+/// to use in filter_map.
 fn filter_delta<'a>(x: (&IdType, &'a RSprocess)) -> Option<&'a RSset> {
     use super::structure::RSprocess::*;
     let (id, rest) = x;
@@ -182,8 +184,8 @@ pub fn lollipops_only_loop_decomposed(
 // Named versions
 // -----------------------------------------------------------------------------
 
-/// finds only the rules symb = pre(Q, rec(symb)), get symb from a translator
+/// Finds only the rules symb = pre(Q, rec(symb)), get symb from a translator
-/// to use in filter_map
+/// to use in filter_map.
 fn filter_delta_named<'a>(
     x: (&IdType, &'a RSprocess),
     symb: &IdType

src/rsprocess/rsdot.rs

@@ -1,7 +1,6 @@
 //! Slightly modified Simple graphviz dot file format output.
 //! See petgraph::dot::mod.
 
-// use alloc::string::String;
 use core::fmt::{self, Display, Write};
 use petgraph::
 {

src/rsprocess/serialize.rs

@@ -1,9 +1,15 @@
+//! Definitions for serializing and deserializing graph and translator.
+//!
+//! N.B. after serialization the size of the graph may be much larger than
+//! before since a lot of ```Rc``` are used in ```RSsystem```.
+
 use std::io;
 
 use petgraph::Graph;
 use serde::{Deserialize, Serialize};
 
-use super::{structure::{RSlabel, RSsystem}, translator::Translator};
+use super::{structure::{RSlabel, RSsystem},
+	    translator::Translator};
 
 #[derive(Serialize, Deserialize)]
 struct GraphAndTranslator {
@@ -11,7 +17,12 @@ struct GraphAndTranslator {
     translator: Translator
 }
 
-pub fn sr<W>(writer: W, graph: &Graph<RSsystem, RSlabel>, translator: &Translator) -> Result<(), serde_cbor_2::Error>
+/// Serializer for graph and translator.
+pub fn sr<W>(
+    writer: W,
+    graph: &Graph<RSsystem, RSlabel>,
+    translator: &Translator
+) -> Result<(), serde_cbor_2::Error>
 where
     W: io::Write,
 {
@@ -22,6 +33,7 @@ where
 			    })
 }
 
+/// Deserializer for file that contains graph and translator.
 pub fn dsr<R>(
     reader: R
 ) -> Result<(Graph<RSsystem, RSlabel>, Translator), serde_cbor_2::Error>

src/rsprocess/statistics.rs

@@ -1,9 +1,11 @@
+//! Non simulated statistics of a system.
+
 use super::structure::RSset;
 use super::structure::RSsystem;
 use super::translator;
 use super::translator::Translator;
 
-/// Returns statistics about the system
+/// Returns statistics about the system.
 /// see main_do(stat,MissingE)
 #[allow(non_snake_case)]
 pub fn of_RSsystem<'a>(translator: &'a Translator, system: &'a RSsystem) -> String {

src/rsprocess/structure.rs

@@ -1,3 +1,5 @@
+//! Module for all basic structures.
+
 use super::translator::IdType;
 use std::collections::{BTreeSet, HashMap, VecDeque};
 use std::hash::Hash;
@@ -8,7 +10,9 @@ use serde::{Deserialize, Serialize};
 // RSset
 // -----------------------------------------------------------------------------
 
-#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+/// Basic set of entities.
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize,
+	 Deserialize)]
 pub struct RSset {
     pub identifiers: BTreeSet<IdType>,
 }
@@ -126,6 +130,8 @@ impl IntoIterator for RSset {
 // -----------------------------------------------------------------------------
 // RSreaction
 // -----------------------------------------------------------------------------
+
+/// Basic structure for a reaction.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct RSreaction {
     pub reactants: RSset,
@@ -167,6 +173,7 @@ impl Default for RSreaction {
 // -----------------------------------------------------------------------------
 // RSprocess
 // -----------------------------------------------------------------------------
+
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub enum RSprocess {
     Nill,

src/rsprocess/support_structures.rs

@@ -1,7 +1,10 @@
+//! Module for helper structure for simulation
+
 use super::structure::{RSlabel, RSprocess, RSset, RSsystem};
 use super::transitions::unfold;
 use std::rc::Rc;
 
+/// 
 #[derive(Clone, Debug)]
 pub struct TransitionsIterator<'a> {
     choices_iterator: std::vec::IntoIter<(Rc<RSset>, Rc<RSprocess>)>,
@@ -25,6 +28,7 @@ impl<'a> TransitionsIterator<'a> {
 impl<'a> Iterator for TransitionsIterator<'a> {
     type Item = (RSlabel, RSsystem);
 
+    /// Creates the next arc from the current system.
     fn next(&mut self) -> Option<(RSlabel, RSsystem)> {
         let (c, k) = self.choices_iterator.next()?;
         let t = self.system.available_entities.union(c.as_ref());

src/rsprocess/transitions.rs

@@ -1,3 +1,5 @@
+//! Definitions for simple simulation steps.
+
 use super::structure::{RSchoices,
 		       RSenvironment,
 		       RSlabel,
@@ -9,7 +11,7 @@ use std::rc::Rc;
 
 /// unfold returns the list of choices for the context given the process
 /// definitions environment. RSchoices is a list of context moves mapping a set
-/// of entities and the continuation
+/// of entities and the continuation.
 /// see unfold
 pub fn unfold(
     environment: &RSenvironment,

src/rsprocess/translator.rs

@@ -1,4 +1,5 @@
 //! Module for translation and keeping track of strings.
+
 use std::{cmp::max, collections::HashMap};
 use serde::{Serialize, Deserialize};
 
@@ -7,6 +8,8 @@ static PRECISION: &usize = &2;
 
 pub type IdType = u32;
 
+/// Structure that keeps track of association string and id. Ids given
+/// sequentially from 0.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct Translator {
     strings: HashMap<String, IdType>,