dds/README.org

* dds: A Home-made Toolkit for Discrete Dynamical Systems in Racket
This is a toolkit for playing with various discrete dynamical systems
in [[https://racket-lang.org/][Racket]].  A discrete dynamical system is a system which evolves from
a discrete state to some other discrete states (many or one).  The
systems are discrete in the sense that we can identify successive
states with no other states in between.  Equivalently, the phase state
of the system is discrete (and is often called the state graph).
These constraints imply the possibility of associating discrete,
possibly branching timelines to any evolution of the system.

*DISCLAIMER:* I develop this toolkit as a support for my research on
discrete dynamical systems.  The primary objective for this framework
is to fit my approach to these systems.  Essentially, this framework
should fit to the "shape of my mind", which is not necessarily the
same as yours.

Currently, the toolkit includes the following files:

  - [[file:generic.rkt][generic.rkt]]: The generic interface for a discrete dynamical
    system, with functions for constructing state graphs.
  - [[file:utils.rkt][utils.rkt]]: Misc utility functions.
  - [[file:networks.rkt][networks.rkt]]: Implements network-based models, which generalise
    Boolean networks, threshold Boolean automata networks, multivalued
    networks, etc.
  - [[file:rs.rkt][rs.rkt]]: Implements reaction systems, a variant of set rewriting.

The toolkit is designed with Emacs [[https://orgmode.org/][Org-mode]] interoperability in mind.
The file [[file:example/example.org][example/example.org]] explains the features available for
interaction with Org-mode.

** Roadmap
   Here is my current roadmap for this toolkit, in order.  The first
   element is what I am currently working on.  The degree of certainty
   that I work on the subsequent items decreases with their position
   in the list.

*** TODO Write new functions for building the interaction graphs
    1. =variables-interact?=
    2. =get-interaction-sign=
    3. =build-interaction-graph=

    I currently have two different kinds of function for building
    interaction graphs: the syntactic interaction graphs and the
    interaction graphs as typically defined in the papers.  These two
    kinds of graphs are not exactly the same.  I have already started
    marking the split by renaming the original
    =build-interaction-graph= to =build-syntactic-interaction-graph=.
    The other functions are somewhat badly structured, somewhat badly
    written, and potentially somewhat wrong.

*** TODO Add variable domains to the network
    I currently define a network as a mapping from variables to
    functions, but in fact I very often need the /domains/ of the
    variables for very many operations.

    I started this transformation a couple of days ago, and decided
    against it, because I thought that some networks may have
    unbounded domains.  That's right, but stays hypothetical, while
    right now I need domains with my networks all the time.

*** TODO Review =build-interaction-graph=
    Check that the definition of this function really follows the
    definition of the interaction graph.  Pay attention to the
    existential vs. universal quantifiers.

*** TODO Start writing the docs properly with Scribble
    Convert some of the comments to Scribble, in particular
    module-level comments introducing the modules and each of
    the sections.

    Set up the infrastructure for extracting the in-source comments
    using [[https://docs.racket-lang.org/scribble/srcdoc.html][this]].

*** TODO Think about /not/ using generics for the dynamics
    Typed Racket can now type classes, and I can implement the idea
    from the module =generics= as a class.  However, I got this advice
    on Racket Users group:

    #+BEGIN_QUOTE
    If you don't need to support arbitrary user implementations, you
    can avoid generics and classes altogether and use structs whose
    fields contain functions.
    #+END_QUOTE

    I will need to think about simpler implementations of the
    interface to dynamics, which should also be simpler to type.

*** TODO Convert =dds= to Typed Racket
    This will necessarily lead to updates in the comments, which
    should be rewritten with Scribble.

    I will do the conversion in the directory =typed/=, by
    incrementally translating existing modules, definition
    by definition.

    The order I will convert the modules:

    1. =utils=
    2. =functions=
    3. the module defining the interface to dynamics (currently =generics=)
    4. =networks=
    5. =rs=

*** TODO Split =networks= into general networks and threshold Boolean networks
*** TODO Submit =update-graph= to =stchang=
*** TODO Implement the BN \to RS conversion
*** TODO Implement the minimisation of TBF/SBF
*** TODO Contribute to Racket
    - Make sequence-filter allow multivalued sequences, provided the
      arity of the predicate is consistent with the arity of
      the sequence.
    - Add a sequence->hash function that accepts a multivalued
      sequence of keys and values (exactly like what in-hash produces)
      and copies them into a hash table.
*** TODO Test network inference with [[https://docs.racket-lang.org/racklog/index.html][Racklog]]