#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))))
]}

@defproc[(union-products [rs ReactionSystem] [as (Listof ReactionName)])
			 (Setof Species)]{

Returns the union of the product sets of the given reactions listed in
@racket[as] in @racket[rs].  If no reactions are supplied, returns the
empty set.

@ex[
(union-products (hash 'a (make-reaction '(x) '(y) '(z))
                      'b (make-reaction '(x y) '() '(z)))
                '(a b))
]}

@defproc[(apply-rs [rs ReactionSystem] [s (Setof Species)])
		   (Setof Species)]{

Applies the reaction system @racket[rs] to @racket[s].

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


@section{Org-mode interaction}

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

@defproc[(str-triple->reaction [lst (List String String String)]) Reaction]{

Converts a triple of strings to a reaction.

@ex[
(str-triple->reaction '("a b" "c d" "e f"))
]}

@defproc[(ht-str-triples->rs [ht (HashTable ReactionName (List String String String))])
			     ReactionSystem]{

Converts a hash table mapping reaction names to triples of strings to
a reaction system.

@ex[
(ht-str-triples->rs (hash 'a (list "x y" "" "k i")
                          'b (list "" "x y" "t j")))
]}

@defproc[(read-org-rs [str String]) ReactionSystem]{

Reads a reaction system from an Org-mode style string.

@ex[
(read-org-rs "((\"a\" \"x t\" \"y\" \"z\") (\"b\" \"x\" \"q\" \"z\"))")
]}

@defproc[(read-context-sequence [str String]) (Listof (Setof Species))]{

Reads a context sequence (a list of sets of species) from a string
containing a list, which may be produced by Org-mode.

@ex[
(read-context-sequence "((\"x y\") (\"z\") (\"\") (\"t\"))")
]}

@defproc[(reaction->str-triple [r Reaction]) (Listof String)]{

Converts a reaction to a triple of strings.

@ex[
(reaction->str-triple (make-reaction '(x y) '(z t) '(k i)))
]}


@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.