dds/scribblings/rs.scrbl

#lang scribble/manual
@(require scribble/example racket/sandbox
	  (for-label typed/racket/base
	  	     (submod "../rs.rkt" typed)))

@(define rs-evaluator
  (parameterize ([sandbox-output 'string]
  		 [sandbox-error-output 'string]
		 [sandbox-memory-limit 500])
   (make-evaluator 'typed/racket #:requires '((submod "rs.rkt" typed)))))

@(define-syntax-rule (ex . args)
  (examples #:eval rs-evaluator . args))

@(define-syntax-rule (deftypeform . args)
  (defform #:kind "type" . args))

@(define-syntax-rule (deftype . args)
  (defidform #:kind "type" . args))

@title[#:tag "rs"]{dds/rs: Reaction Systems}

@defmodule[(submod dds/rs typed)]

This module defines reaction systems and various tools for working with them.

@section[#:tag "rs-basics"]{Basic definitions}

@deftype[Species]{

A synonym of @racket[Symbol].

}

@defstruct*[reaction ([reactants (Setof Species)]
		      [inhibitors (Setof Species)]
		      [products (Setof Species)])]{

A reaction is a triple of sets, giving the reactants, the inhibitors,
and the products, respectively.

}

@deftype[Reaction]{

The type of the instances of @racket[reaction].

}

@deftype[ReactionName]{

A reaction name is any @racket[Symbol].

}

@defproc[(make-reaction [r (Listof Reaction)]
			[i (Listof Reaction)]
			[p (Listof Reaction)])
			Reaction]{

A shortcut for constructing @racket[Reaction]s using list syntax
instead of set syntax.

@ex[
(make-reaction '(a b) '(c d) '(e f))
]}

@defproc[(enabled? [r Reaction] [s (Setof Species)]) Boolean]{

A @racket[Reaction] is enabled on a set of species if all of its
reactants are in the set and none of its inhibitors are.

@ex[
(enabled? (make-reaction '(a b) '(c d) '())
          (set 'a 'b 'e))
(enabled? (make-reaction '(a b) '(c d) '())
          (set 'a 'b 'c))
(enabled? (make-reaction '(a b) '(c d) '())
          (set 'b 'e))
]}

@deftype[ReactionSystem]{

A reaction system is a dictionary mapping @racket[ReactionName]s to
@racket[Reaction]s.

}

@defproc[(list-enabled [rs ReactionSystem] [s (Setof Species)])
		       (Listof ReactionName)]{

Returns the list of the names of reactions of @racket[rs] enabled on
@racket[s].

@ex[
(let ([rs (hash 'a (make-reaction '(x) '(y) '(z))
                'b (make-reaction '(x y) '() '(z)))])
  (values (list-enabled rs (set 'x 'y))
          (list-enabled rs (set 'x))))
]}



@section{Org-mode interaction}

This section contains some useful primitives for
@hyperlink["https://orgmode.org/"]{Org-mode} interoperability.

@section{Dynamics of reaction systems}

The dynamics of reaction systems is typically defined as @emph{interaction
processes}.  An interactive process of a reaction system is a sequence of
states driven by a sequence of contexts in the following way.  The reaction
system starts with the initial context.  Then, at every step, the result of
applying the reaction system is merged with the next element of the context
sequence, and the reaction system is then applied to the result of the union.
If the sequence of contexts is empty, the reaction system cannot evolve.