Debriefing - Geogi/CriojoSC GitHub Wiki

Criojo and CriojoSC


Criojo is a chemical programming language. A chemical program is written with rules akin to chemical reactions, except that the molecules embed a state which the products use.

For instance, the duplicate removal program can be simply written as: R(x) & R(x) --> R(x)

This is because whenever the rule executes, the x state is the same in the three occurences of R(x). So the reactants have to be in the same state (it’s a duplicate), and they are consummed to produce only one molecule in the same state. When the rule stops executing, all duplicates are gone.

For more information, see (fr).


CriojoSC is an implementation of Criojo in Scala (

It reduces the complexity of coding with pure chemical rules (which are fully expressive nonetheless) by allowing to use the underlying Scala or Java language.

For instance, if F is a native Java binary function compatible with the type of x, then R(x) --> T(F(x)) is correct CriojoSC code.

CriojoSC is developped in a git repository located at It is GPL licenced so the code can be forked, modified and redistributed under the licence agreement.

To fork a GitHub repository, just click the top-right button labelled “Fork”.


Follow these steps (assuming Linux/Mac):

  1. cd <workspace>

    Replace <workspace> by the directory you usually put your sources in.

  2. sudo <package-manager:install> git sbt

    Install git and SBT ( Replace <package-manager:install> by your package manager install command. For instance:

    • Debian, Ubuntu: apt-get install
    • Fedora: yum install
    • Gentoo: emerge
    • Arch: pacman -S
    • MacPorts: port install
    • Homebrew: brew install
  3. git clone

    Clone (download a copy of) the CriojoSC repository in your workspace.

  4. cd CriojoSC
  5. ~export SBT_OPTS=”-Xms512M -Xmx1536M -Xss1M -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=384M”~

    SBT uses a lot more memory than what the JVM allows by default. These options (which are passed by SBT to java) avoid it to fail due to memory shortage.

  6. sbt generate/run test

    This will generate the source (there are a few classes automatically generated), compile it and run the specifications (tests). All should pass.

Source structure

File structure

The top-level directory contains the following items:

  • generate/: Source code generator. It’s needed for compiling CriojoSC but is not directly related to chemical programming. It is a simple wrapper on Scalate (
  • main/: The source of CriojoSC. See Package structure for details.
  • project/: The SBT project definition. It simply defines how to run the code generator and where the main sources are.
  • .gitignore: git will ignore these patterns when adding.
  • .travis.yml: We use an external continuous integration build: This is its configuration file.
  • COPYING.txt: The GPL licence.
  • build.sbt: General SBT configuration keys.

Package structure

The top-level package is fr.emn.criojosc. The package fr.emn.criojosc.generate is special as it contains the code generator (which is only a build dependency), all other sub-packages are part of the source.


The top-level package object does not contain any class, but it makes visible those needed for coding:

  • Relation factory from model.relation
  • Variable factory from model.pattern
  • Nip, alias of NilPatternList from model.pattern.list
  • S, alias of Successor from model.pattern

It also provides the following utility functions:

  • engine is a factory on the default (best working) verbose Engine implementation
  • agent is a factory for agents that allows mixing rules and closed reactants (for the initial solution) using the two implicits rule2left and cr2right.
  • namedAgent does the same but also gives the agent a name.

See the respective package for details.


This package contains the classes that describe a chemical program, but not its execution. All of them are immutable (if I’m not mistaken; but if one is mutable it’s a bug).

  • Agent: an agent contains rules and reactants. Unless it receives messages (which are not implemented at this point), it’s a closed box in which the rules all run until the chemical equilibrium is reached. In that prospect, it’s the smallest type of chemical programs.
  • ClosedReactant: like a molecule, but may have a state (in the same way classes can have attributes).
  • Engine: the interface of engines (see =fr.emn.criojosc.engine=) which run any number of agents.
  • Guard: the interface of guards. In a rule, a guard is a condition that can prevent the rule from running even when all open reactants are matched.
  • OpenReactant: a pattern of molecule. Since closed reactants can have a state, it is possible to create a pattern of such states to match specific molecules. Open reactants can only be used in the left part of the rule (what a chemical equation calls “reactant”).
  • Pattern: the interface of patterns, which are used with open reactants to match a closed reactant state.
  • RelationSymbol: designates the R in R(x).
  • Rule: the Criojo equivalent to chemical equations.
  • Valuation: a store for variables values (variables are a special kind of pattern).

The package also defines the following subpackages:

  • atom: default implementation for closed and open reactants. The other implementation (not present) would be messages.
  • guard: all types of guards (conjunctions, control guards, equivalences, native guards).
  • output: several traits that are only needed for debugging (add optional strings).
  • pattern: implementations for several types of patterns. Of note:
    • Variable: the most important pattern, matches everything and stores the matched value in a valuation. Matching results can be filtered with constructors (see below) and executions with guards.
    • Constructors: patterns that filter the matching results of other patterns, e.g. Successor or ListPattern.
    • TuplePattern: they’re constructors, but it’s worth mentionning that it’s one of the few generated sources (because of a Scala limitation on tuples). For that reason, never edit TuplePatterns.scala, make your modifications in TuplePatterns.ssp (using Scalate’s templating syntax) and re-run sbt generate/run.
    • Const: only match the one value they were created with.
  • relation: typed implementations for relations. The multi-ary implementations are generated from TypedRelations.ssp and the factory from Relation.ssp so edit those templates and not the Scala sources (then run sbt generate/run).
  • rule: the different parts of the rule (premise, conclusion) and some traits to make the syntax clearer.
  • valuation: implementation of valuations.


There are two engines:

  • fr.emn.criojosc.automaton: is a working engine which stores the matches of rule premises in statefull automatons. Because it has to iterate the matches (i.e. valuations) of guards to test them, its complexity is rather bad.
  • fr.emn.criojosc.discrimination: is a work in progress. It wouldn’t need to always read the valuations to test a guard using smarter data structures and leading to a better complexity.

If you speak French, my report contains much more details about these implementations and their differences:

Test packages

The test packages use Specs2 ( and consist of:

  • index: This file generates the index for all other specifications and provides an overview of successes / failures.
  • model: Tests any non trivial class in the model. The structure of packages is the same as the main source.
  • examples: Contains several agents for testing and demonstration purposes. The package object has two configuration keys: which agents to test (testAgents) and which engine to use for that (TestEngine). These keys are used by the EngineSpec in model.

Current state

The model should be stable enough. The automaton engine has a bad complexity, but it passes all tests (so it actually works). Since it’s very permissive, it can actually be used in applications when the number of reactants stays low.

The current work in on the new engine, which works with maps (or discrimination structures) to hopefully achieve a way better complexity. This still requires quite a bit of formal work and should be kept in sync with Prof. Grall’s work.

Sample CriojoSC programs

See the classes in the test package fr.emn.criojosc.examples.


For information, contact me at: mailto:[email protected]. I am more than willing to help with CriojoSC (or any other implementation of Criojo) and will get back to you quickly.

Work I might do alone

As said in Current state, working on the really interesting part (the new engine) is not really feasible without interaction with Prof. Grall. However, I am willing to do quality related stuff on my downtime:

  • Improve the code documentation (at this point only the model has some kind of doc, and still it’s incomplete and somewhat outdated).
  • Write a user-friendly guide to chemical programming and Criojo, then push it to gh-pages (the branch of the repo that is served at, don’t click it right now there’s nothing there).
  • Clean up the code (rewrite some examples that still use the extremely verbose low-level syntax, clean the model without breaking compability, make the verbose and standard automaton engines more conseistent)
  • Improve the build management (specifically avoid having to explicitly run generate, and make it part of the source-generation phase instead).
  • Improve the specifications.
  • Add more examples and provide a way to link them to specifications.
  • Investigate how to make the syntax better (it still requires a lot of parentheses).
⚠️ ** Fallback** ⚠️