#lang scribble/manual
@(require scribble/example racket/sandbox
	  (for-label typed/racket/base
	  	     graph
		     (only-in typed/graph Graph)
		     (submod "../networks.rkt" typed)
		     "../utils.rkt"
		     "../functions.rkt"))

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

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

@title[#:tag "networks"]{dds/networks: Formal Dynamical Networks}

@defmodule[(submod dds/networks typed)]

This module provides definitions for and analysing network models.  A network
is a set of variables which are updated according to their corresponding update
functions.  The variables to be updated at each step are given by the mode.
This model can generalise Boolean networks, TBANs, multivalued networks, etc.

@section[#:tag "networks-basics"]{Basic types}

@defform[#:kind "type" (State a)]{

An immutable mapping (a hash table) assigning elements of type @racket[a] to
the variables.  A synonym of @racket[VariableMapping].

}

@defform[#:kind "type" (UpdateFunction a)]{

An update function is a function computing a value from the given
state.  This is a synonym of the type @racket[(-> (State a) a)].

}

@defform[#:kind "type" (DomainMapping a)]{

A domain mapping is a hash table mapping variables to the lists of values in
their domains.

}

@defstruct*[network ([functions (VariableMapping (UpdateFunction a))]
		     [domains (DomainMapping a)])]{

A network consists of a mapping from its variables to its update variables, as
a well as of a mapping from its variables to their domains.

Instances of @racket[network] have the type @racket[Network].

}

@defidform[#:kind "type" Network]{

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

@ex[
(: or-func (UpdateFunction Boolean))
(define (or-func s)
  (or (hash-ref s 'a) (hash-ref s 'b)))

(: and-func (UpdateFunction Boolean))
(define (and-func s)
  (and (hash-ref s 'a) (hash-ref s 'b)))

(network (hash 'a or-func
               'b and-func)
         (hash 'a '(#f #t)
               'b '(#f #t)))
]}

@section{Constructing networks}

@defproc[(make-same-domains [vars (Listof Variable)]
			    [domain (Listof a)])
			    (DomainMapping a)]{

Makes a hash set mapping all variables to a single domain.

@ex[
(make-same-domains '(a b) '(1 2))
]}

@defproc[(make-boolean-domains [vars (Listof Variable)])
			       (DomainMapping Boolean)]{

Makes a hash set mapping all variables to the Boolean domain.

@ex[
(make-boolean-domains '(a b))
]}

@defproc[(make-boolean-network [vars (VariableMapping (UpdateFunction Boolean))])
 			       (Network Boolean)]{

Builds a Boolean network from a given hash table assigning functions to
variables by attributing Boolean domains to every variable.

@ex[
(: or-func (UpdateFunction Boolean))
(define (or-func s)
  (or (hash-ref s 'a) (hash-ref s 'b)))

(: and-func (UpdateFunction Boolean))
(define (and-func s)
  (and (hash-ref s 'a) (hash-ref s 'b)))

(make-boolean-network (hash 'a or-func 'b and-func))
]}

@section{Syntactic description of networks}

@section{Inferring interaction graphs}

This section provides inference of both unsigned and signed interaction graphs.
Since the inference of signed interaction graphs is based on analysing the
dynamics of the networks, it may be quite resource-consuming, especially since
I allow any syntactic forms in the definitions of the functions.

Note the fine difference between @emph{syntactic} interaction graphs and
interaction graphs generated from the dynamics of the network.
Syntactic interaction graphs are based on the whether a variable appears or not
in the form of the function for another variable.  On the other hand, the
normal, conventional interaction graph records the fact that one variable has
an impact on the dynamics of the other variable.  Depending on the model, these
may or may not be the same.

@section{Dynamics of networks}

This section contains definitions for building and analysing the dynamics
of networks.

@section{Tabulating functions and networks}

@section{Constructing functions and networks}

@section{Random functions and networks}

@section{TBF/TBN and SBF/SBN}

This section defines threshold Boolean functions (TBF) and networks (TBN), as
well as sign Boolean functions (SBF) and networks (SBN).