Added some documentation on scripts to use and how to run it and install

it

doc/_build/html/_sources/components.txt

@@ -1,17 +1,59 @@
 Modelverse components
 =====================
 
-Modelverse State
-----------------
+The Modelverse consists of three individual projects, which are linked together to construct the Modelverse.
+Each of these projects stands alone and has its own concerns.
+A socket interface to communicate with the other components is provided.
+By using sockets, it becomes possible to switch everything about the implementation, even the implementation language, without endangering interoperability.
+
+The three projects are:
+1. Modelverse State
+2. Modelverse Kernel
+3. Modelverse Interface
+
+.. image:: img/overview.svg
+
+Modelverse State (MvS)
+----------------------
+
+The Modelverse State implements the data storage features of the Modelverse.
+To the Modelverse State, all data needs to be representable as a graph, which it will manipulate.
+
+All basic, and some composite, operations are implemented on this graph, such as creating nodes and edges, reading them, and deleting them.
 
 Interface
 ^^^^^^^^^
 
-Modelverse Kernel
------------------
+All communication happens through sockets, using XML/HTTP Requests.
+(TODO)
+
+Modelverse Kernel (MvK)
+-----------------------
+
+The Modelverse Kernel communicates with the MvS and interprets its data.
+The Modelverse Kernel has no way of storing data, except by sending it to the MvS for storage.
+Through this architecture, the MvK becomes completely stateless and easily replacable.
+
+For the MvK, a set of rules is defined which tell it how to interpret the graph in the MvS.
+Complex programs can be written by encoding the program as a graph, and letting the MvK interpret it.
+
+To allow for maximal flexibility, the MvK can never expose the users to the internal identifier of the MvS, which the MvK uses.
+This allows the MvS to internally restructure itself without having to worry about stale references elsewhere.
 
 Interface
 ^^^^^^^^^
 
-Modelverse Interface
---------------------
+All communication happens through sockets, using XML/HTTP Requests.
+(TODO)
+
+Modelverse Interface (MvI)
+--------------------------
+
+The Modelverse Interface is the part that most users will be using.
+It presents a textual or graphical interface to the Modelverse itself.
+Depending on the interface, the MvK and MvS will serve only as a repository (heavy client), or they serve as the tool itself (thin client).
+Either way, the communication is identical, just the granularity differs, and the place where the algorithms are implemented.
+
+Traditionally, the MvI is a compiler that compiles some code to either a graph, or operations for the MvK.
+This can, however, be any possible kind of tool, or even combination of multiple tools.
+For example, a graphical tool could serve as an interface to the Modelverse, where it just processes the graphical events and sends the desired operations (such as creating an element) to the Modelverse.

doc/_build/html/_sources/howto.txt

@@ -1,9 +1,179 @@
 How to run
 ==========
 
-Understanding the components
-----------------------------
+Running the Modelverse is all done through the use of scripts to coordinate the three different projects.
 
-Scripts
--------
+The following scripts are included by default.
 
+check_objects.py
+----------------
+
+Checks whether all compiled objects can be found, and if their symbol table does not contain undefined references.
+This script cannot be executed directly and is only a helper.
+
+compile.py
+----------
+
+Compiles the provided code with the selected mode.
+This should also not be called by end-users, though it is possible.
+
+Invocation::
+
+    python scripts/compile.py address file username object mode
+
+============== ====================================== =====================
+Parameter name Description                            Example              
+============== ====================================== =====================
+address        Address of the Modelverse              http://localhost:8001
+file           File to be compiled                    file.alc             
+username       Username to use when compiling         test_user            
+object         Object name to export to               object.o             
+mode           Either CO (constructors) or PO (graph) PO                   
+============== ====================================== =====================
+
+execute_model.py
+----------------
+
+Compile a model and action language files together, executing the action language.
+First, all models are added, and then the action language is executed, starting at function "main".
+Models being created are temporary, so they need to be exported before they can be accessed in the action language.
+
+Invocation::
+
+    python scripts/execute_model.py address username file1 file2 ...
+
+============== ======================================= =====================
+Parameter name Description                             Example
+============== ======================================= =====================
+address        Address of the Modelverse               http://localhost:8001
+username       Username to use when compiling          test
+file           File to compile (either .mvc or .alc)   test.alc
+============== ======================================= =====================
+
+fix_files.py
+------------
+
+Fix some files that must be kept identical.
+This is sometimes necessary because if a file gets updated, the changes must propagate.
+Usually, this is done with symbolic links or similar, but there does not seem to be a nice cross-platform way of doing this in Git.
+
+Invocation::
+    
+    python scripts/fix_files.py
+
+flush_compiler_caches.py
+------------------------
+
+Clear all cached files from the compiler.
+The compiler will automatically reparse files when they have been changed, but changes to the compiler code itself will not be detected.
+When changing the compiler, this file should be executed to flush these file caches.
+
+Invocation::
+
+    python scripts/flush_compiler_caches.py
+
+generate_bootstrap.py
+---------------------
+
+Creates the bootstrap file for the Modelverse State.
+This creates the necessary initial graph which contains links to all primitive code that is executed by the Modelverse before users can communicate with it.
+Generally, this needs to be executed when any file in the *bootstrap/* folder is modified.
+Compilation is fairly smart, only recompiling parts that have changed.
+
+Invocation::
+    
+    python scripts/generate_bootstrap.py
+
+link_and_load.py
+----------------
+
+This takes a set of objects in the Modelverse, links them together in a single "executable" and executes it immediately.
+Generally not needed by end-users.
+
+Invocation::
+
+    python scripts/link_and_load.py address username object1 object2 ...
+
+============== ======================================= =====================
+Parameter name Description                             Example
+============== ======================================= =====================
+address        Address of the Modelverse               http://localhost:8001
+username       Username to use when compiling          test
+object         File to compile (either .mvc or .alc)   test.alc
+============== ======================================= =====================
+
+make_all.py
+-----------
+
+Compile a set of files and executes them immediately.
+This uses constructors by default, which is the most elegant, but also the slowest.
+
+Invocation::
+
+    python scripts/make_all.py address username file1 file2 ...
+
+============== ======================================= =====================
+Parameter name Description                             Example
+============== ======================================= =====================
+address        Address of the Modelverse               http://localhost:8001
+username       Username to use when compiling          test
+file           File to compile (either .mvc or .alc)   test.alc
+============== ======================================= =====================
+
+make_parallel.py
+----------------
+
+A parallel version of make_all.py.
+This uses the direct graph compilation, and compiles these graphs in parallel.
+This is much faster than make_all, though much less elegant.
+
+Invocation::
+
+    python scripts/make_parallel.py address username file1 file2 ...
+
+============== ======================================= =====================
+Parameter name Description                             Example
+============== ======================================= =====================
+address        Address of the Modelverse               http://localhost:8001
+username       Username to use when compiling          test
+file           File to compile (either .mvc or .alc)   test.alc
+============== ======================================= =====================
+
+prompt.py
+---------
+
+A generic prompt interface to the Modelverse.
+You can log in as a specific user and start sending input messages to the Modelverse as that user.
+All output sent by the Modelverse will be printed in the console.
+There is no logic in the prompt itself, making it completely generic.
+
+Invocation::
+
+    python scripts/prompt.py
+
+run_local_modelverse.py
+-----------------------
+
+Locally runs an instance of the Modelverse at the requested port.
+This combines MvK and MvS at the same system, and actually makes a direct link between them, omitting the slow use of sockets.
+While this is kind of a hack at the moment, it is really necessary with the current low performance.
+To split them up, there just needs to be a statechart in between both of them (which is already written and working).
+
+Invocation::
+
+    python scripts/run_local_modelverse.py port
+
+============== ============================== =======
+Parameter name Description                    Example
+============== ============================== =======
+port           Port to host the Modelverse on 8001
+============== ============================== =======
+
+run_tests.py
+------------
+
+Run the tests for all parts of the Modelverse.
+
+Invocation::
+
+    python scripts/run_tests.py

doc/_build/html/components.html

@@ -51,20 +51,49 @@
             
   <div class="section" id="modelverse-components">
 <h1>Modelverse components<a class="headerlink" href="#modelverse-components" title="Permalink to this headline">¶</a></h1>
-<div class="section" id="modelverse-state">
-<h2>Modelverse State<a class="headerlink" href="#modelverse-state" title="Permalink to this headline">¶</a></h2>
+<p>The Modelverse consists of three individual projects, which are linked together to construct the Modelverse.
+Each of these projects stands alone and has its own concerns.
+A socket interface to communicate with the other components is provided.
+By using sockets, it becomes possible to switch everything about the implementation, even the implementation language, without endangering interoperability.</p>
+<p>The three projects are:
+1. Modelverse State
+2. Modelverse Kernel
+3. Modelverse Interface</p>
+<img alt="_images/overview.svg" src="_images/overview.svg" /><div class="section" id="modelverse-state-mvs">
+<h2>Modelverse State (MvS)<a class="headerlink" href="#modelverse-state-mvs" title="Permalink to this headline">¶</a></h2>
+<p>The Modelverse State implements the data storage features of the Modelverse.
+To the Modelverse State, all data needs to be representable as a graph, which it will manipulate.</p>
+<p>All basic, and some composite, operations are implemented on this graph, such as creating nodes and edges, reading them, and deleting them.</p>
 <div class="section" id="interface">
 <h3>Interface<a class="headerlink" href="#interface" title="Permalink to this headline">¶</a></h3>
+<p>All communication happens through sockets, using XML/HTTP Requests.
+(TODO)</p>
 </div>
 </div>
-<div class="section" id="modelverse-kernel">
-<h2>Modelverse Kernel<a class="headerlink" href="#modelverse-kernel" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="modelverse-kernel-mvk">
+<h2>Modelverse Kernel (MvK)<a class="headerlink" href="#modelverse-kernel-mvk" title="Permalink to this headline">¶</a></h2>
+<p>The Modelverse Kernel communicates with the MvS and interprets its data.
+The Modelverse Kernel has no way of storing data, except by sending it to the MvS for storage.
+Through this architecture, the MvK becomes completely stateless and easily replacable.</p>
+<p>For the MvK, a set of rules is defined which tell it how to interpret the graph in the MvS.
+Complex programs can be written by encoding the program as a graph, and letting the MvK interpret it.</p>
+<p>To allow for maximal flexibility, the MvK can never expose the users to the internal identifier of the MvS, which the MvK uses.
+This allows the MvS to internally restructure itself without having to worry about stale references elsewhere.</p>
 <div class="section" id="id1">
 <h3>Interface<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<p>All communication happens through sockets, using XML/HTTP Requests.
+(TODO)</p>
 </div>
 </div>
-<div class="section" id="modelverse-interface">
-<h2>Modelverse Interface<a class="headerlink" href="#modelverse-interface" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="modelverse-interface-mvi">
+<h2>Modelverse Interface (MvI)<a class="headerlink" href="#modelverse-interface-mvi" title="Permalink to this headline">¶</a></h2>
+<p>The Modelverse Interface is the part that most users will be using.
+It presents a textual or graphical interface to the Modelverse itself.
+Depending on the interface, the MvK and MvS will serve only as a repository (heavy client), or they serve as the tool itself (thin client).
+Either way, the communication is identical, just the granularity differs, and the place where the algorithms are implemented.</p>
+<p>Traditionally, the MvI is a compiler that compiles some code to either a graph, or operations for the MvK.
+This can, however, be any possible kind of tool, or even combination of multiple tools.
+For example, a graphical tool could serve as an interface to the Modelverse, where it just processes the graphical events and sends the desired operations (such as creating an element) to the Modelverse.</p>
 </div>
 </div>
 
@@ -77,15 +106,15 @@
   <h3><a href="index.html">Table Of Contents</a></h3>
   <ul>
 <li><a class="reference internal" href="#">Modelverse components</a><ul>
-<li><a class="reference internal" href="#modelverse-state">Modelverse State</a><ul>
+<li><a class="reference internal" href="#modelverse-state-mvs">Modelverse State (MvS)</a><ul>
 <li><a class="reference internal" href="#interface">Interface</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#modelverse-kernel">Modelverse Kernel</a><ul>
+<li><a class="reference internal" href="#modelverse-kernel-mvk">Modelverse Kernel (MvK)</a><ul>
 <li><a class="reference internal" href="#id1">Interface</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#modelverse-interface">Modelverse Interface</a></li>
+<li><a class="reference internal" href="#modelverse-interface-mvi">Modelverse Interface (MvI)</a></li>
 </ul>
 </li>
 </ul>

doc/_build/html/howto.html

@@ -51,11 +51,282 @@
             
   <div class="section" id="how-to-run">
 <h1>How to run<a class="headerlink" href="#how-to-run" title="Permalink to this headline">¶</a></h1>
-<div class="section" id="understanding-the-components">
-<h2>Understanding the components<a class="headerlink" href="#understanding-the-components" title="Permalink to this headline">¶</a></h2>
+<p>Running the Modelverse is all done through the use of scripts to coordinate the three different projects.</p>
+<p>The following scripts are included by default.</p>
+<div class="section" id="check-objects-py">
+<h2>check_objects.py<a class="headerlink" href="#check-objects-py" title="Permalink to this headline">¶</a></h2>
+<p>Checks whether all compiled objects can be found, and if their symbol table does not contain undefined references.
+This script cannot be executed directly and is only a helper.</p>
+</div>
+<div class="section" id="compile-py">
+<h2>compile.py<a class="headerlink" href="#compile-py" title="Permalink to this headline">¶</a></h2>
+<p>Compiles the provided code with the selected mode.
+This should also not be called by end-users, though it is possible.</p>
+<p>Invocation:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">python</span> <span class="n">scripts</span><span class="o">/</span><span class="nb">compile</span><span class="o">.</span><span class="n">py</span> <span class="n">address</span> <span class="n">file</span> <span class="n">username</span> <span class="nb">object</span> <span class="n">mode</span>
+</pre></div>
+</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="19%" />
+<col width="52%" />
+<col width="29%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Parameter name</th>
+<th class="head">Description</th>
+<th class="head">Example</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>address</td>
+<td>Address of the Modelverse</td>
+<td><a class="reference external" href="http://localhost:8001">http://localhost:8001</a></td>
+</tr>
+<tr class="row-odd"><td>file</td>
+<td>File to be compiled</td>
+<td>file.alc</td>
+</tr>
+<tr class="row-even"><td>username</td>
+<td>Username to use when compiling</td>
+<td>test_user</td>
+</tr>
+<tr class="row-odd"><td>object</td>
+<td>Object name to export to</td>
+<td>object.o</td>
+</tr>
+<tr class="row-even"><td>mode</td>
+<td>Either CO (constructors) or PO (graph)</td>
+<td>PO</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="execute-model-py">
+<h2>execute_model.py<a class="headerlink" href="#execute-model-py" title="Permalink to this headline">¶</a></h2>
+<p>Compile a model and action language files together, executing the action language.
+First, all models are added, and then the action language is executed, starting at function &#8220;main&#8221;.
+Models being created are temporary, so they need to be exported before they can be accessed in the action language.</p>
+<p>Invocation:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">python</span> <span class="n">scripts</span><span class="o">/</span><span class="n">execute_model</span><span class="o">.</span><span class="n">py</span> <span class="n">address</span> <span class="n">username</span> <span class="n">file1</span> <span class="n">file2</span> <span class="o">...</span>
+</pre></div>
+</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="19%" />
+<col width="53%" />
+<col width="28%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Parameter name</th>
+<th class="head">Description</th>
+<th class="head">Example</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>address</td>
+<td>Address of the Modelverse</td>
+<td><a class="reference external" href="http://localhost:8001">http://localhost:8001</a></td>
+</tr>
+<tr class="row-odd"><td>username</td>
+<td>Username to use when compiling</td>
+<td>test</td>
+</tr>
+<tr class="row-even"><td>file</td>
+<td>File to compile (either .mvc or .alc)</td>
+<td>test.alc</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="fix-files-py">
+<h2>fix_files.py<a class="headerlink" href="#fix-files-py" title="Permalink to this headline">¶</a></h2>
+<p>Fix some files that must be kept identical.
+This is sometimes necessary because if a file gets updated, the changes must propagate.
+Usually, this is done with symbolic links or similar, but there does not seem to be a nice cross-platform way of doing this in Git.</p>
+<p>Invocation:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">python</span> <span class="n">scripts</span><span class="o">/</span><span class="n">fix_files</span><span class="o">.</span><span class="n">py</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="flush-compiler-caches-py">
+<h2>flush_compiler_caches.py<a class="headerlink" href="#flush-compiler-caches-py" title="Permalink to this headline">¶</a></h2>
+<p>Clear all cached files from the compiler.
+The compiler will automatically reparse files when they have been changed, but changes to the compiler code itself will not be detected.
+When changing the compiler, this file should be executed to flush these file caches.</p>
+<p>Invocation:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">python</span> <span class="n">scripts</span><span class="o">/</span><span class="n">flush_compiler_caches</span><span class="o">.</span><span class="n">py</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="generate-bootstrap-py">
+<h2>generate_bootstrap.py<a class="headerlink" href="#generate-bootstrap-py" title="Permalink to this headline">¶</a></h2>
+<p>Creates the bootstrap file for the Modelverse State.
+This creates the necessary initial graph which contains links to all primitive code that is executed by the Modelverse before users can communicate with it.
+Generally, this needs to be executed when any file in the <em>bootstrap/</em> folder is modified.
+Compilation is fairly smart, only recompiling parts that have changed.</p>
+<p>Invocation:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">python</span> <span class="n">scripts</span><span class="o">/</span><span class="n">generate_bootstrap</span><span class="o">.</span><span class="n">py</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="link-and-load-py">
+<h2>link_and_load.py<a class="headerlink" href="#link-and-load-py" title="Permalink to this headline">¶</a></h2>
+<p>This takes a set of objects in the Modelverse, links them together in a single &#8220;executable&#8221; and executes it immediately.
+Generally not needed by end-users.</p>
+<p>Invocation:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">python</span> <span class="n">scripts</span><span class="o">/</span><span class="n">link_and_load</span><span class="o">.</span><span class="n">py</span> <span class="n">address</span> <span class="n">username</span> <span class="n">object1</span> <span class="n">object2</span> <span class="o">...</span>
+</pre></div>
+</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="19%" />
+<col width="53%" />
+<col width="28%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Parameter name</th>
+<th class="head">Description</th>
+<th class="head">Example</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>address</td>
+<td>Address of the Modelverse</td>
+<td><a class="reference external" href="http://localhost:8001">http://localhost:8001</a></td>
+</tr>
+<tr class="row-odd"><td>username</td>
+<td>Username to use when compiling</td>
+<td>test</td>
+</tr>
+<tr class="row-even"><td>object</td>
+<td>File to compile (either .mvc or .alc)</td>
+<td>test.alc</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="make-all-py">
+<h2>make_all.py<a class="headerlink" href="#make-all-py" title="Permalink to this headline">¶</a></h2>
+<p>Compile a set of files and executes them immediately.
+This uses constructors by default, which is the most elegant, but also the slowest.</p>
+<p>Invocation:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">python</span> <span class="n">scripts</span><span class="o">/</span><span class="n">make_all</span><span class="o">.</span><span class="n">py</span> <span class="n">address</span> <span class="n">username</span> <span class="n">file1</span> <span class="n">file2</span> <span class="o">...</span>
+</pre></div>
+</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="19%" />
+<col width="53%" />
+<col width="28%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Parameter name</th>
+<th class="head">Description</th>
+<th class="head">Example</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>address</td>
+<td>Address of the Modelverse</td>
+<td><a class="reference external" href="http://localhost:8001">http://localhost:8001</a></td>
+</tr>
+<tr class="row-odd"><td>username</td>
+<td>Username to use when compiling</td>
+<td>test</td>
+</tr>
+<tr class="row-even"><td>file</td>
+<td>File to compile (either .mvc or .alc)</td>
+<td>test.alc</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="make-parallel-py">
+<h2>make_parallel.py<a class="headerlink" href="#make-parallel-py" title="Permalink to this headline">¶</a></h2>
+<p>A parallel version of make_all.py.
+This uses the direct graph compilation, and compiles these graphs in parallel.
+This is much faster than make_all, though much less elegant.</p>
+<p>Invocation:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">python</span> <span class="n">scripts</span><span class="o">/</span><span class="n">make_parallel</span><span class="o">.</span><span class="n">py</span> <span class="n">address</span> <span class="n">username</span> <span class="n">file1</span> <span class="n">file2</span> <span class="o">...</span>
+</pre></div>
+</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="19%" />
+<col width="53%" />
+<col width="28%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Parameter name</th>
+<th class="head">Description</th>
+<th class="head">Example</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>address</td>
+<td>Address of the Modelverse</td>
+<td><a class="reference external" href="http://localhost:8001">http://localhost:8001</a></td>
+</tr>
+<tr class="row-odd"><td>username</td>
+<td>Username to use when compiling</td>
+<td>test</td>
+</tr>
+<tr class="row-even"><td>file</td>
+<td>File to compile (either .mvc or .alc)</td>
+<td>test.alc</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="prompt-py">
+<h2>prompt.py<a class="headerlink" href="#prompt-py" title="Permalink to this headline">¶</a></h2>
+<p>A generic prompt interface to the Modelverse.
+You can log in as a specific user and start sending input messages to the Modelverse as that user.
+All output sent by the Modelverse will be printed in the console.
+There is no logic in the prompt itself, making it completely generic.</p>
+<p>Invocation:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">python</span> <span class="n">scripts</span><span class="o">/</span><span class="n">prompt</span><span class="o">.</span><span class="n">py</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="run-local-modelverse-py">
+<h2>run_local_modelverse.py<a class="headerlink" href="#run-local-modelverse-py" title="Permalink to this headline">¶</a></h2>
+<p>Locally runs an instance of the Modelverse at the requested port.
+This combines MvK and MvS at the same system, and actually makes a direct link between them, omitting the slow use of sockets.
+While this is kind of a hack at the moment, it is really necessary with the current low performance.
+To split them up, there just needs to be a statechart in between both of them (which is already written and working).</p>
+<p>Invocation:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">python</span> <span class="n">scripts</span><span class="o">/</span><span class="n">run_local_modelverse</span><span class="o">.</span><span class="n">py</span> <span class="n">port</span>
+</pre></div>
+</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="27%" />
+<col width="59%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Parameter name</th>
+<th class="head">Description</th>
+<th class="head">Example</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>port</td>
+<td>Port to host the Modelverse on</td>
+<td>8001</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="run-tests-py">
+<h2>run_tests.py<a class="headerlink" href="#run-tests-py" title="Permalink to this headline">¶</a></h2>
+<p>Run the tests for all parts of the Modelverse.</p>
+<p>Invocation:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">python</span> <span class="n">scripts</span><span class="o">/</span><span class="n">run_tests</span><span class="o">.</span><span class="n">py</span>
+</pre></div>
 </div>
-<div class="section" id="scripts">
-<h2>Scripts<a class="headerlink" href="#scripts" title="Permalink to this headline">¶</a></h2>
 </div>
 </div>
 
@@ -68,8 +339,18 @@
   <h3><a href="index.html">Table Of Contents</a></h3>
   <ul>
 <li><a class="reference internal" href="#">How to run</a><ul>
-<li><a class="reference internal" href="#understanding-the-components">Understanding the components</a></li>
-<li><a class="reference internal" href="#scripts">Scripts</a></li>
+<li><a class="reference internal" href="#check-objects-py">check_objects.py</a></li>
+<li><a class="reference internal" href="#compile-py">compile.py</a></li>
+<li><a class="reference internal" href="#execute-model-py">execute_model.py</a></li>
+<li><a class="reference internal" href="#fix-files-py">fix_files.py</a></li>
+<li><a class="reference internal" href="#flush-compiler-caches-py">flush_compiler_caches.py</a></li>
+<li><a class="reference internal" href="#generate-bootstrap-py">generate_bootstrap.py</a></li>
+<li><a class="reference internal" href="#link-and-load-py">link_and_load.py</a></li>
+<li><a class="reference internal" href="#make-all-py">make_all.py</a></li>
+<li><a class="reference internal" href="#make-parallel-py">make_parallel.py</a></li>
+<li><a class="reference internal" href="#prompt-py">prompt.py</a></li>
+<li><a class="reference internal" href="#run-local-modelverse-py">run_local_modelverse.py</a></li>
+<li><a class="reference internal" href="#run-tests-py">run_tests.py</a></li>
 </ul>
 </li>
 </ul>

doc/_build/html/index.html

@@ -57,14 +57,24 @@
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="components.html">Modelverse components</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="components.html#modelverse-state">Modelverse State</a></li>
-<li class="toctree-l2"><a class="reference internal" href="components.html#modelverse-kernel">Modelverse Kernel</a></li>
-<li class="toctree-l2"><a class="reference internal" href="components.html#modelverse-interface">Modelverse Interface</a></li>
+<li class="toctree-l2"><a class="reference internal" href="components.html#modelverse-state-mvs">Modelverse State (MvS)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="components.html#modelverse-kernel-mvk">Modelverse Kernel (MvK)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="components.html#modelverse-interface-mvi">Modelverse Interface (MvI)</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="howto.html">How to run</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="howto.html#understanding-the-components">Understanding the components</a></li>
-<li class="toctree-l2"><a class="reference internal" href="howto.html#scripts">Scripts</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto.html#check-objects-py">check_objects.py</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto.html#compile-py">compile.py</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto.html#execute-model-py">execute_model.py</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto.html#fix-files-py">fix_files.py</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto.html#flush-compiler-caches-py">flush_compiler_caches.py</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto.html#generate-bootstrap-py">generate_bootstrap.py</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto.html#link-and-load-py">link_and_load.py</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto.html#make-all-py">make_all.py</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto.html#make-parallel-py">make_parallel.py</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto.html#prompt-py">prompt.py</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto.html#run-local-modelverse-py">run_local_modelverse.py</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto.html#run-tests-py">run_tests.py</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="actionlanguage.html">Action Language</a><ul>

doc/components.rst

@@ -1,17 +1,59 @@
 Modelverse components
 =====================
 
-Modelverse State
-----------------
+The Modelverse consists of three individual projects, which are linked together to construct the Modelverse.
+Each of these projects stands alone and has its own concerns.
+A socket interface to communicate with the other components is provided.
+By using sockets, it becomes possible to switch everything about the implementation, even the implementation language, without endangering interoperability.
+
+The three projects are:
+1. Modelverse State
+2. Modelverse Kernel
+3. Modelverse Interface
+
+.. image:: img/overview.svg
+
+Modelverse State (MvS)
+----------------------
+
+The Modelverse State implements the data storage features of the Modelverse.
+To the Modelverse State, all data needs to be representable as a graph, which it will manipulate.
+
+All basic, and some composite, operations are implemented on this graph, such as creating nodes and edges, reading them, and deleting them.
 
 Interface
 ^^^^^^^^^
 
-Modelverse Kernel
------------------
+All communication happens through sockets, using XML/HTTP Requests.
+(TODO)
+
+Modelverse Kernel (MvK)
+-----------------------
+
+The Modelverse Kernel communicates with the MvS and interprets its data.
+The Modelverse Kernel has no way of storing data, except by sending it to the MvS for storage.
+Through this architecture, the MvK becomes completely stateless and easily replacable.
+
+For the MvK, a set of rules is defined which tell it how to interpret the graph in the MvS.
+Complex programs can be written by encoding the program as a graph, and letting the MvK interpret it.
+
+To allow for maximal flexibility, the MvK can never expose the users to the internal identifier of the MvS, which the MvK uses.
+This allows the MvS to internally restructure itself without having to worry about stale references elsewhere.
 
 Interface
 ^^^^^^^^^
 
-Modelverse Interface
---------------------
+All communication happens through sockets, using XML/HTTP Requests.
+(TODO)
+
+Modelverse Interface (MvI)
+--------------------------
+
+The Modelverse Interface is the part that most users will be using.
+It presents a textual or graphical interface to the Modelverse itself.
+Depending on the interface, the MvK and MvS will serve only as a repository (heavy client), or they serve as the tool itself (thin client).
+Either way, the communication is identical, just the granularity differs, and the place where the algorithms are implemented.
+
+Traditionally, the MvI is a compiler that compiles some code to either a graph, or operations for the MvK.
+This can, however, be any possible kind of tool, or even combination of multiple tools.
+For example, a graphical tool could serve as an interface to the Modelverse, where it just processes the graphical events and sends the desired operations (such as creating an element) to the Modelverse.

doc/howto.rst

@@ -1,9 +1,179 @@
 How to run
 ==========
 
-Understanding the components
-----------------------------
+Running the Modelverse is all done through the use of scripts to coordinate the three different projects.
 
-Scripts
--------
+The following scripts are included by default.
 
+check_objects.py
+----------------
+
+Checks whether all compiled objects can be found, and if their symbol table does not contain undefined references.
+This script cannot be executed directly and is only a helper.
+
+compile.py
+----------
+
+Compiles the provided code with the selected mode.
+This should also not be called by end-users, though it is possible.
+
+Invocation::
+
+    python scripts/compile.py address file username object mode
+
+============== ====================================== =====================
+Parameter name Description                            Example              
+============== ====================================== =====================
+address        Address of the Modelverse              http://localhost:8001
+file           File to be compiled                    file.alc             
+username       Username to use when compiling         test_user            
+object         Object name to export to               object.o             
+mode           Either CO (constructors) or PO (graph) PO                   
+============== ====================================== =====================
+
+execute_model.py
+----------------
+
+Compile a model and action language files together, executing the action language.
+First, all models are added, and then the action language is executed, starting at function "main".
+Models being created are temporary, so they need to be exported before they can be accessed in the action language.
+
+Invocation::
+
+    python scripts/execute_model.py address username file1 file2 ...
+
+============== ======================================= =====================
+Parameter name Description                             Example
+============== ======================================= =====================
+address        Address of the Modelverse               http://localhost:8001
+username       Username to use when compiling          test
+file           File to compile (either .mvc or .alc)   test.alc
+============== ======================================= =====================
+
+fix_files.py
+------------
+
+Fix some files that must be kept identical.
+This is sometimes necessary because if a file gets updated, the changes must propagate.
+Usually, this is done with symbolic links or similar, but there does not seem to be a nice cross-platform way of doing this in Git.
+
+Invocation::
+    
+    python scripts/fix_files.py
+
+flush_compiler_caches.py
+------------------------
+
+Clear all cached files from the compiler.
+The compiler will automatically reparse files when they have been changed, but changes to the compiler code itself will not be detected.
+When changing the compiler, this file should be executed to flush these file caches.
+
+Invocation::
+
+    python scripts/flush_compiler_caches.py
+
+generate_bootstrap.py
+---------------------
+
+Creates the bootstrap file for the Modelverse State.
+This creates the necessary initial graph which contains links to all primitive code that is executed by the Modelverse before users can communicate with it.
+Generally, this needs to be executed when any file in the *bootstrap/* folder is modified.
+Compilation is fairly smart, only recompiling parts that have changed.
+
+Invocation::
+    
+    python scripts/generate_bootstrap.py
+
+link_and_load.py
+----------------
+
+This takes a set of objects in the Modelverse, links them together in a single "executable" and executes it immediately.
+Generally not needed by end-users.
+
+Invocation::
+
+    python scripts/link_and_load.py address username object1 object2 ...
+
+============== ======================================= =====================
+Parameter name Description                             Example
+============== ======================================= =====================
+address        Address of the Modelverse               http://localhost:8001
+username       Username to use when compiling          test
+object         File to compile (either .mvc or .alc)   test.alc
+============== ======================================= =====================
+
+make_all.py
+-----------
+
+Compile a set of files and executes them immediately.
+This uses constructors by default, which is the most elegant, but also the slowest.
+
+Invocation::
+
+    python scripts/make_all.py address username file1 file2 ...
+
+============== ======================================= =====================
+Parameter name Description                             Example
+============== ======================================= =====================
+address        Address of the Modelverse               http://localhost:8001
+username       Username to use when compiling          test
+file           File to compile (either .mvc or .alc)   test.alc
+============== ======================================= =====================
+
+make_parallel.py
+----------------
+
+A parallel version of make_all.py.
+This uses the direct graph compilation, and compiles these graphs in parallel.
+This is much faster than make_all, though much less elegant.
+
+Invocation::
+
+    python scripts/make_parallel.py address username file1 file2 ...
+
+============== ======================================= =====================
+Parameter name Description                             Example
+============== ======================================= =====================
+address        Address of the Modelverse               http://localhost:8001
+username       Username to use when compiling          test
+file           File to compile (either .mvc or .alc)   test.alc
+============== ======================================= =====================
+
+prompt.py
+---------
+
+A generic prompt interface to the Modelverse.
+You can log in as a specific user and start sending input messages to the Modelverse as that user.
+All output sent by the Modelverse will be printed in the console.
+There is no logic in the prompt itself, making it completely generic.
+
+Invocation::
+
+    python scripts/prompt.py
+
+run_local_modelverse.py
+-----------------------
+
+Locally runs an instance of the Modelverse at the requested port.
+This combines MvK and MvS at the same system, and actually makes a direct link between them, omitting the slow use of sockets.
+While this is kind of a hack at the moment, it is really necessary with the current low performance.
+To split them up, there just needs to be a statechart in between both of them (which is already written and working).
+
+Invocation::
+
+    python scripts/run_local_modelverse.py port
+
+============== ============================== =======
+Parameter name Description                    Example
+============== ============================== =======
+port           Port to host the Modelverse on 8001
+============== ============================== =======
+
+run_tests.py
+------------
+
+Run the tests for all parts of the Modelverse.
+
+Invocation::
+
+    python scripts/run_tests.py