2.2.9.4. causality/Stochsim.hpp

2.2.9.4.1. Class causality::MassActionKinetics

class causality::MassActionKinetics

A helper class for performing stochastic simulations where events are drawn according to the law of mass action. Importantly, if the underlying derivation graph is enlarged then syncSize() must be called before calling draw().

2.2.9.4.1.1. Synopsis

struct MOD_DECL MassActionKinetics {
    MassActionKinetics(std::shared_ptr<dg::DG> dg_, std::function<double(dg::DG::HyperEdge)> rate);
    ~MassActionKinetics();
    MassActionKinetics(MassActionKinetics &&);
    MassActionKinetics &operator=(MassActionKinetics &&);
    MassActionKinetics(const MassActionKinetics &);
    MassActionKinetics &operator=(const MassActionKinetics &);
    void syncSize();
    std::pair<dg::DG::HyperEdge, double>
    draw(const std::vector<dg::DG::HyperEdge> &possibles, const PetriNetMarking &m);
private:
    struct Pimpl;
    std::unique_ptr<Pimpl> p;
};

2.2.9.4.1.2. Details

MassActionKinetics(std::shared_ptr<dg::DG> dg_, std::function<double(dg::DG::HyperEdge)> rate)

Construct a new instance, based on the given derivation graph. When evaluating reactions/hyperedges, the given callback is used to set the reaction rate. This rate may be cached by the object.

Throws

LogicError if !dg_.

Throws

LogicError if neither dg_->hasActiveBuilder() nor dg_->isLocked().

Throws

LogicError if !rate.

void syncSize()

Enlarges the internal data structures to the current size of the underlying derivation graph.

std::pair<dg::DG::HyperEdge, double> draw(const std::vector<dg::DG::HyperEdge> &possibles, const PetriNetMarking &m)
Returns

one of the given hyperedges, randomly selected according to the low of mass action based on the given population/marking and the reaction rates. The second returned component is the sum of reactivity for the given reactions/hyperedges.

Use rngReseed() to seed the pseudo-random bit generator used for the selection.

Throws

LogicError if possibles.empty().

Throws

LogicError if an edge in possibles is null.

Throws

LogicError if an edge in possibles does not belong to the underlying derivation graph.

Throws

LogicError if m is not a marking on the underlying derivation graph.

Requires syncSize() to have been called since the last time the underlying derivation graph has changed size.

2.2.9.4.2. Class causality::EventTrace

class causality::EventTrace

A helper class to hold an initial state with a subsequent trace of events. An event is either a reaction/hyperedge being performed (an EdgeEvent) or a transfer of tokens out or in to the system (a TransferEvent).

2.2.9.4.2.1. Synopsis

struct MOD_DECL EventTrace {
    struct EdgeEvent {
        double time;
        dg::DG::HyperEdge edge;
    public:
        MOD_DECL friend bool operator==(const EdgeEvent &a, const EdgeEvent &b);
        MOD_DECL friend bool operator!=(const EdgeEvent &a, const EdgeEvent &b);
        MOD_DECL friend std::ostream &operator<<(std::ostream &s, const EdgeEvent &e);
    };
    struct TransferEvent {
        double time;
        dg::DG::Vertex vertex;
        int count;
    public:
        MOD_DECL friend bool operator==(const TransferEvent &a, const TransferEvent &b);
        MOD_DECL friend bool operator!=(const TransferEvent &a, const TransferEvent &b);
        MOD_DECL friend std::ostream &operator<<(std::ostream &s, const TransferEvent &e);
    };
    using Event = boost::variant<EdgeEvent, TransferEvent>;
    struct iterator : boost::iterator_facade<iterator, Event, std::random_access_iterator_tag, Event> {
        iterator();
        iterator(const EventTrace *t, int offset);
    private:
        friend class boost::iterator_core_access;
        Event dereference() const;
        bool equal(iterator other) const;
        void increment();
        // TODO: implement the rest to make it a true random-access iterator
        void advance(int n);
    private:
        const EventTrace *t;
        int offset;
    };
    using const_iterator = iterator;
public:
    EventTrace(const PetriNetMarking &initialState);
    ~EventTrace();
    EventTrace(EventTrace &&);
    EventTrace &operator=(EventTrace &&);
    EventTrace(const EventTrace &);
    EventTrace &operator=(const EventTrace &);
public:
    PetriNetMarking getInitialState() const;
    int size() const;
    const_iterator begin() const;
    const_iterator end() const;
    Event operator[](int i) const;
    MOD_DECL friend std::ostream &operator<<(std::ostream &s, const EventTrace &t);
public:
    void addEdge(double time, dg::DG::HyperEdge e);
    void addTransfer(double time, dg::DG::Vertex v, int count);
public:
    std::string print() const;
private:
    struct Pimpl;
    std::unique_ptr<Pimpl> p;
};

2.2.9.4.2.2. Details

using Event = boost::variant<EdgeEvent, TransferEvent>
type iterator
using const_iterator = iterator
EventTrace(PetriNetMarking initialState)

Construct an empty event trace with an initial state. A copy of the given marking is being stored.

PetriNetMarking getInitialState() const
Returns

a copy of the initial state for this event trace.

int size() const
Returns

the number of events in the trace.

const_iterator begin() const
const_iterator end() const
Returns

the begin/end iterator for the range of events in the trace.

Event operator[](int i) const
Returns

the ith event in the trace.

Throws

LogicError if i is out of bounds.

friend std::ostream &operator<<(std::ostream &s, const EventTrace &t)
void addEdge(double time, dg::DG::HyperEdge e)

Append an edge event to the trace.

Throws

LogicError if !e.

Throws

LogicError if e does not belong to the underlying derivation graph.

void addTransfer(double time, dg::DG::Vertex v, int count)

Append a transfer event to the trace. The count may be negative for extraction and positive for input.

Throws

LogicError if !v.

Throws

LogicError if v does not belong to the underlying derivation graph.

std::string print() const

Create a plot of the counts throughout the event trace at each time point. If the times given to addEdge() and addTransfer() at any point were decreasing or below 0, the resulting plot may fail to compile or look strange.

Returns

the filename for the PDF that will be compiled by the post processor.

2.2.9.4.3. Class causality::EventTrace::EdgeEvent

class causality::EventTrace::EdgeEvent
double time
dg::DG::HyperEdge edge

2.2.9.4.4. Class causality::EventTrace::TransferEvent

class causality::EventTrace::TransferEvent
double time
dg::DG::Vertex vertex
int count