Basic documentation of the modelling language

doc/_build/html/_sources/index.txt

@@ -20,11 +20,3 @@ Contents:
    Advanced examples <advanced>
    Common problems and solutions <problems>
    Internal workings <internal>
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

doc/_build/html/_sources/modellanguage.txt

@@ -1,17 +1,174 @@
 Modelling Language
 ==================
 
+Apart from the action language, the Modelverse also has a modelling language.
+With this language, models (*i.e.*, data) can be defined in addition to the algorithms.
+
+This language is still mostly work in progress, but should be decent enough to construct simple metamodels and instantiate them.
+All models have the extension \*.mvc, indicating that they are models and should be compiled as such.
+
 Language description
 --------------------
 
+The modelling language defines data structures, which will be formed as models in the Modelverse.
+
+Several constructs are supported.
+
+Import
+^^^^^^
+
+An import pulls in a model and makes it accessible using a simpler identifier.
+The structure is as follows::
+
+    import path/in/modelverse as my_model
+
+After this import, the model that was previously exported to *path/in/modelverse* becomes available as *my_model*.
+
+Include
+^^^^^^^
+
+When combined with action language, the action language might require some includes of header files.
+To do this, the includes can be placed at the top of the hierarchy.
+
+Model
+^^^^^
+
+Every model is defined by first specifying the type of model to instantiate, followed by the name of the model to create.
+The name of the model can then later on be referenced in other models (as type, or for exporting).
+Within the model, all names of the type model can be used as types again.
+
+Instance
+^^^^^^^^
+
+A model consists of some instances.
+These instances are instances of types specified by the model that is the metaclass of the current model.
+
+Attribute
+^^^^^^^^^
+
+Each model instance can contain attributes.
+There are two kinds of attributes: defining attributes, or value attributes.
+
+For defining attributes, the structure is as follows::
+
+    Class A{
+        my_parameter : ParameterType
+    }
+
+This defines a parameter called *my_parameter* which is typed by *ParameterType*.
+*ParameterType* must always be a type defined in the type that is being instantiated.
+Even if this is a primitive, such as *Integer*, the metamodel must define what it calls an *Integer*.
+While this might seem bothersome, this clearly defines the notion of what a type means, without having to resort to the implementation.
+
+Value attributes are similar, but have a different syntax, and contain an actual value.
+Their structure is as follows::
+
+    A a{
+        my_parameter = 1
+    }
+
+They assign a value to a previously defined attribute.
+In this case, it is important that the value conforms to the type specified in the defining attribute.
+
 Merge with Action Language
 --------------------------
 
+It is of course possible to incorporate action language inside of a model.
+A typical use case for this is the definition of constraints or actions.
+Action language is surrounded by dollar signs ($), which causes the parser to redirect the text between dollar signs to the action language parser.
+All includes necessary for the compilation of the action code, must be provided at the top of the document.
+
 Examples
 --------
 
+Some simple examples of models are provided below.
+This code only makes the specified models available in code; to do something with these models, an algorithms has to read out the model and operate on it.
+
 Petri Net metamodel
 ^^^^^^^^^^^^^^^^^^^
 
+A simple Petri Net metamodel can be created, based on the SimpleClassDiagrams metamodel.
+This looks like this::
+
+    import models/SimpleClassDiagrams as SCD
+
+    SCD PetriNets{
+        Class Natural {}
+        Class Place{
+            tokens : Natural
+        }
+        Class Transition{}
+        Association P2T (Place, Transition) {
+            weight : Natural
+        }
+        Association T2P (Transition, Place) {
+            weight : Natural
+        }
+    }
+
+    export PetriNets to models/PetriNets
+
+Note that in this metamodel, there is no constraint placed on the value of a Natural: it can literaly be anything.
+That is why usually, you want to place constraints on the value.
+In this case, the value needs to be an integer, and it must be larger than or equal to zero.
+Such constraints are written in the action language, surrounded by dollar signs::
+
+    import models/SimpleClassDiagrams as SCD
+    include "primitives.alh"
+
+    SCD PetriNets{
+        Class Natural {
+            $
+                if (bool_not(is_physical_int(self))):
+                    return "Natural has no integer value at " + name!
+                elif (integer_lt(self, 0)):
+                    return "Natural does not have a positive or zero value at " + name!
+                else:
+                    return "OK"!
+             $
+        }
+        Class Place{
+            tokens : Natural {
+                target_lower_cardinality = 1
+                target_upper_cardinality = 1
+                }
+        }
+        Class Transition{}
+        Association P2T (Place, Transition) {
+            weight : Natural {
+                target_lower_cardinality = 1
+                target_upper_cardinality = 1
+                }
+        }
+        Association T2P (Transition, Place) {
+            weight : Natural {
+                target_lower_cardinality = 1
+                target_upper_cardinality = 1
+                }
+        }
+    }
+
 Petri Net instance
 ^^^^^^^^^^^^^^^^^^
+
+The previous metamodel can then be instantiated::
+
+    import models/PetriNets as PetriNets
+
+    PetriNets my_petrinet {
+        Place p1 {
+            tokens = 1
+        }
+        Place p2 {
+            tokens = 3
+        }
+        Transition t1 {}
+        P2T (p1, t1) {
+            weight = 1
+        }
+        T2P (t1, p2) {
+            weight = 2
+        }
+    }
+
+    export my_petrinet to models/my_petrinet

doc/_build/html/index.html

@@ -105,14 +105,6 @@
 <li class="toctree-l1"><a class="reference internal" href="internal.html">Internal workings</a></li>
 </ul>
 </div>
-</div>
-<div class="section" id="indices-and-tables">
-<h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this headline">¶</a></h1>
-<ul class="simple">
-<li><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></li>
-<li><a class="reference internal" href="py-modindex.html"><span class="std std-ref">Module Index</span></a></li>
-<li><a class="reference internal" href="search.html"><span class="std std-ref">Search Page</span></a></li>
-</ul>
 </div>
 
 
@@ -121,12 +113,6 @@
       </div>
       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
         <div class="sphinxsidebarwrapper">
-  <h3><a href="#">Table Of Contents</a></h3>
-  <ul>
-<li><a class="reference internal" href="#">Welcome to Modelverse&#8217;s documentation!</a></li>
-<li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>
-</ul>
-
   <h4>Next topic</h4>
   <p class="topless"><a href="installation.html"
                         title="next chapter">Installation</a></p>

doc/_build/html/modellanguage.html

@@ -51,19 +51,163 @@
             
   <div class="section" id="modelling-language">
 <h1>Modelling Language<a class="headerlink" href="#modelling-language" title="Permalink to this headline">¶</a></h1>
+<p>Apart from the action language, the Modelverse also has a modelling language.
+With this language, models (<em>i.e.</em>, data) can be defined in addition to the algorithms.</p>
+<p>This language is still mostly work in progress, but should be decent enough to construct simple metamodels and instantiate them.
+All models have the extension *.mvc, indicating that they are models and should be compiled as such.</p>
 <div class="section" id="language-description">
 <h2>Language description<a class="headerlink" href="#language-description" title="Permalink to this headline">¶</a></h2>
+<p>The modelling language defines data structures, which will be formed as models in the Modelverse.</p>
+<p>Several constructs are supported.</p>
+<div class="section" id="import">
+<h3>Import<a class="headerlink" href="#import" title="Permalink to this headline">¶</a></h3>
+<p>An import pulls in a model and makes it accessible using a simpler identifier.
+The structure is as follows:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">path</span><span class="o">/</span><span class="ow">in</span><span class="o">/</span><span class="n">modelverse</span> <span class="k">as</span> <span class="n">my_model</span>
+</pre></div>
+</div>
+<p>After this import, the model that was previously exported to <em>path/in/modelverse</em> becomes available as <em>my_model</em>.</p>
+</div>
+<div class="section" id="include">
+<h3>Include<a class="headerlink" href="#include" title="Permalink to this headline">¶</a></h3>
+<p>When combined with action language, the action language might require some includes of header files.
+To do this, the includes can be placed at the top of the hierarchy.</p>
+</div>
+<div class="section" id="model">
+<h3>Model<a class="headerlink" href="#model" title="Permalink to this headline">¶</a></h3>
+<p>Every model is defined by first specifying the type of model to instantiate, followed by the name of the model to create.
+The name of the model can then later on be referenced in other models (as type, or for exporting).
+Within the model, all names of the type model can be used as types again.</p>
+</div>
+<div class="section" id="instance">
+<h3>Instance<a class="headerlink" href="#instance" title="Permalink to this headline">¶</a></h3>
+<p>A model consists of some instances.
+These instances are instances of types specified by the model that is the metaclass of the current model.</p>
+</div>
+<div class="section" id="attribute">
+<h3>Attribute<a class="headerlink" href="#attribute" title="Permalink to this headline">¶</a></h3>
+<p>Each model instance can contain attributes.
+There are two kinds of attributes: defining attributes, or value attributes.</p>
+<p>For defining attributes, the structure is as follows:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">Class</span> <span class="n">A</span><span class="p">{</span>
+    <span class="n">my_parameter</span> <span class="p">:</span> <span class="n">ParameterType</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This defines a parameter called <em>my_parameter</em> which is typed by <em>ParameterType</em>.
+<em>ParameterType</em> must always be a type defined in the type that is being instantiated.
+Even if this is a primitive, such as <em>Integer</em>, the metamodel must define what it calls an <em>Integer</em>.
+While this might seem bothersome, this clearly defines the notion of what a type means, without having to resort to the implementation.</p>
+<p>Value attributes are similar, but have a different syntax, and contain an actual value.
+Their structure is as follows:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">A</span> <span class="n">a</span><span class="p">{</span>
+    <span class="n">my_parameter</span> <span class="o">=</span> <span class="mi">1</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>They assign a value to a previously defined attribute.
+In this case, it is important that the value conforms to the type specified in the defining attribute.</p>
+</div>
 </div>
 <div class="section" id="merge-with-action-language">
 <h2>Merge with Action Language<a class="headerlink" href="#merge-with-action-language" title="Permalink to this headline">¶</a></h2>
+<p>It is of course possible to incorporate action language inside of a model.
+A typical use case for this is the definition of constraints or actions.
+Action language is surrounded by dollar signs ($), which causes the parser to redirect the text between dollar signs to the action language parser.
+All includes necessary for the compilation of the action code, must be provided at the top of the document.</p>
 </div>
 <div class="section" id="examples">
 <h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
+<p>Some simple examples of models are provided below.
+This code only makes the specified models available in code; to do something with these models, an algorithms has to read out the model and operate on it.</p>
 <div class="section" id="petri-net-metamodel">
 <h3>Petri Net metamodel<a class="headerlink" href="#petri-net-metamodel" title="Permalink to this headline">¶</a></h3>
+<p>A simple Petri Net metamodel can be created, based on the SimpleClassDiagrams metamodel.
+This looks like this:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">models</span><span class="o">/</span><span class="n">SimpleClassDiagrams</span> <span class="k">as</span> <span class="n">SCD</span>
+
+<span class="n">SCD</span> <span class="n">PetriNets</span><span class="p">{</span>
+    <span class="n">Class</span> <span class="n">Natural</span> <span class="p">{}</span>
+    <span class="n">Class</span> <span class="n">Place</span><span class="p">{</span>
+        <span class="n">tokens</span> <span class="p">:</span> <span class="n">Natural</span>
+    <span class="p">}</span>
+    <span class="n">Class</span> <span class="n">Transition</span><span class="p">{}</span>
+    <span class="n">Association</span> <span class="n">P2T</span> <span class="p">(</span><span class="n">Place</span><span class="p">,</span> <span class="n">Transition</span><span class="p">)</span> <span class="p">{</span>
+        <span class="n">weight</span> <span class="p">:</span> <span class="n">Natural</span>
+    <span class="p">}</span>
+    <span class="n">Association</span> <span class="n">T2P</span> <span class="p">(</span><span class="n">Transition</span><span class="p">,</span> <span class="n">Place</span><span class="p">)</span> <span class="p">{</span>
+        <span class="n">weight</span> <span class="p">:</span> <span class="n">Natural</span>
+    <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="n">export</span> <span class="n">PetriNets</span> <span class="n">to</span> <span class="n">models</span><span class="o">/</span><span class="n">PetriNets</span>
+</pre></div>
+</div>
+<p>Note that in this metamodel, there is no constraint placed on the value of a Natural: it can literaly be anything.
+That is why usually, you want to place constraints on the value.
+In this case, the value needs to be an integer, and it must be larger than or equal to zero.
+Such constraints are written in the action language, surrounded by dollar signs:</p>
+<div class="highlight-default"><div class="highlight"><pre>import models/SimpleClassDiagrams as SCD
+include &quot;primitives.alh&quot;
+
+SCD PetriNets{
+    Class Natural {
+        $
+            if (bool_not(is_physical_int(self))):
+                return &quot;Natural has no integer value at &quot; + name!
+            elif (integer_lt(self, 0)):
+                return &quot;Natural does not have a positive or zero value at &quot; + name!
+            else:
+                return &quot;OK&quot;!
+         $
+    }
+    Class Place{
+        tokens : Natural {
+            target_lower_cardinality = 1
+            target_upper_cardinality = 1
+            }
+    }
+    Class Transition{}
+    Association P2T (Place, Transition) {
+        weight : Natural {
+            target_lower_cardinality = 1
+            target_upper_cardinality = 1
+            }
+    }
+    Association T2P (Transition, Place) {
+        weight : Natural {
+            target_lower_cardinality = 1
+            target_upper_cardinality = 1
+            }
+    }
+}
+</pre></div>
+</div>
 </div>
 <div class="section" id="petri-net-instance">
 <h3>Petri Net instance<a class="headerlink" href="#petri-net-instance" title="Permalink to this headline">¶</a></h3>
+<p>The previous metamodel can then be instantiated:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">models</span><span class="o">/</span><span class="n">PetriNets</span> <span class="k">as</span> <span class="n">PetriNets</span>
+
+<span class="n">PetriNets</span> <span class="n">my_petrinet</span> <span class="p">{</span>
+    <span class="n">Place</span> <span class="n">p1</span> <span class="p">{</span>
+        <span class="n">tokens</span> <span class="o">=</span> <span class="mi">1</span>
+    <span class="p">}</span>
+    <span class="n">Place</span> <span class="n">p2</span> <span class="p">{</span>
+        <span class="n">tokens</span> <span class="o">=</span> <span class="mi">3</span>
+    <span class="p">}</span>
+    <span class="n">Transition</span> <span class="n">t1</span> <span class="p">{}</span>
+    <span class="n">P2T</span> <span class="p">(</span><span class="n">p1</span><span class="p">,</span> <span class="n">t1</span><span class="p">)</span> <span class="p">{</span>
+        <span class="n">weight</span> <span class="o">=</span> <span class="mi">1</span>
+    <span class="p">}</span>
+    <span class="n">T2P</span> <span class="p">(</span><span class="n">t1</span><span class="p">,</span> <span class="n">p2</span><span class="p">)</span> <span class="p">{</span>
+        <span class="n">weight</span> <span class="o">=</span> <span class="mi">2</span>
+    <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="n">export</span> <span class="n">my_petrinet</span> <span class="n">to</span> <span class="n">models</span><span class="o">/</span><span class="n">my_petrinet</span>
+</pre></div>
+</div>
 </div>
 </div>
 </div>
@@ -77,7 +221,14 @@
   <h3><a href="index.html">Table Of Contents</a></h3>
   <ul>
 <li><a class="reference internal" href="#">Modelling Language</a><ul>
-<li><a class="reference internal" href="#language-description">Language description</a></li>
+<li><a class="reference internal" href="#language-description">Language description</a><ul>
+<li><a class="reference internal" href="#import">Import</a></li>
+<li><a class="reference internal" href="#include">Include</a></li>
+<li><a class="reference internal" href="#model">Model</a></li>
+<li><a class="reference internal" href="#instance">Instance</a></li>
+<li><a class="reference internal" href="#attribute">Attribute</a></li>
+</ul>
+</li>
 <li><a class="reference internal" href="#merge-with-action-language">Merge with Action Language</a></li>
 <li><a class="reference internal" href="#examples">Examples</a><ul>
 <li><a class="reference internal" href="#petri-net-metamodel">Petri Net metamodel</a></li>

doc/index.rst

@@ -20,11 +20,3 @@ Contents:
    Advanced examples <advanced>
    Common problems and solutions <problems>
    Internal workings <internal>
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

doc/modellanguage.rst

@@ -1,17 +1,174 @@
 Modelling Language
 ==================
 
+Apart from the action language, the Modelverse also has a modelling language.
+With this language, models (*i.e.*, data) can be defined in addition to the algorithms.
+
+This language is still mostly work in progress, but should be decent enough to construct simple metamodels and instantiate them.
+All models have the extension \*.mvc, indicating that they are models and should be compiled as such.
+
 Language description
 --------------------
 
+The modelling language defines data structures, which will be formed as models in the Modelverse.
+
+Several constructs are supported.
+
+Import
+^^^^^^
+
+An import pulls in a model and makes it accessible using a simpler identifier.
+The structure is as follows::
+
+    import path/in/modelverse as my_model
+
+After this import, the model that was previously exported to *path/in/modelverse* becomes available as *my_model*.
+
+Include
+^^^^^^^
+
+When combined with action language, the action language might require some includes of header files.
+To do this, the includes can be placed at the top of the hierarchy.
+
+Model
+^^^^^
+
+Every model is defined by first specifying the type of model to instantiate, followed by the name of the model to create.
+The name of the model can then later on be referenced in other models (as type, or for exporting).
+Within the model, all names of the type model can be used as types again.
+
+Instance
+^^^^^^^^
+
+A model consists of some instances.
+These instances are instances of types specified by the model that is the metaclass of the current model.
+
+Attribute
+^^^^^^^^^
+
+Each model instance can contain attributes.
+There are two kinds of attributes: defining attributes, or value attributes.
+
+For defining attributes, the structure is as follows::
+
+    Class A{
+        my_parameter : ParameterType
+    }
+
+This defines a parameter called *my_parameter* which is typed by *ParameterType*.
+*ParameterType* must always be a type defined in the type that is being instantiated.
+Even if this is a primitive, such as *Integer*, the metamodel must define what it calls an *Integer*.
+While this might seem bothersome, this clearly defines the notion of what a type means, without having to resort to the implementation.
+
+Value attributes are similar, but have a different syntax, and contain an actual value.
+Their structure is as follows::
+
+    A a{
+        my_parameter = 1
+    }
+
+They assign a value to a previously defined attribute.
+In this case, it is important that the value conforms to the type specified in the defining attribute.
+
 Merge with Action Language
 --------------------------
 
+It is of course possible to incorporate action language inside of a model.
+A typical use case for this is the definition of constraints or actions.
+Action language is surrounded by dollar signs ($), which causes the parser to redirect the text between dollar signs to the action language parser.
+All includes necessary for the compilation of the action code, must be provided at the top of the document.
+
 Examples
 --------
 
+Some simple examples of models are provided below.
+This code only makes the specified models available in code; to do something with these models, an algorithms has to read out the model and operate on it.
+
 Petri Net metamodel
 ^^^^^^^^^^^^^^^^^^^
 
+A simple Petri Net metamodel can be created, based on the SimpleClassDiagrams metamodel.
+This looks like this::
+
+    import models/SimpleClassDiagrams as SCD
+
+    SCD PetriNets{
+        Class Natural {}
+        Class Place{
+            tokens : Natural
+        }
+        Class Transition{}
+        Association P2T (Place, Transition) {
+            weight : Natural
+        }
+        Association T2P (Transition, Place) {
+            weight : Natural
+        }
+    }
+
+    export PetriNets to models/PetriNets
+
+Note that in this metamodel, there is no constraint placed on the value of a Natural: it can literaly be anything.
+That is why usually, you want to place constraints on the value.
+In this case, the value needs to be an integer, and it must be larger than or equal to zero.
+Such constraints are written in the action language, surrounded by dollar signs::
+
+    import models/SimpleClassDiagrams as SCD
+    include "primitives.alh"
+
+    SCD PetriNets{
+        Class Natural {
+            $
+                if (bool_not(is_physical_int(self))):
+                    return "Natural has no integer value at " + name!
+                elif (integer_lt(self, 0)):
+                    return "Natural does not have a positive or zero value at " + name!
+                else:
+                    return "OK"!
+             $
+        }
+        Class Place{
+            tokens : Natural {
+                target_lower_cardinality = 1
+                target_upper_cardinality = 1
+                }
+        }
+        Class Transition{}
+        Association P2T (Place, Transition) {
+            weight : Natural {
+                target_lower_cardinality = 1
+                target_upper_cardinality = 1
+                }
+        }
+        Association T2P (Transition, Place) {
+            weight : Natural {
+                target_lower_cardinality = 1
+                target_upper_cardinality = 1
+                }
+        }
+    }
+
 Petri Net instance
 ^^^^^^^^^^^^^^^^^^
+
+The previous metamodel can then be instantiated::
+
+    import models/PetriNets as PetriNets
+
+    PetriNets my_petrinet {
+        Place p1 {
+            tokens = 1
+        }
+        Place p2 {
+            tokens = 3
+        }
+        Transition t1 {}
+        P2T (p1, t1) {
+            weight = 1
+        }
+        T2P (t1, p2) {
+            weight = 2
+        }
+    }
+
+    export my_petrinet to models/my_petrinet