Initial commit

doc/staticallocator.rst

@@ -0,0 +1,72 @@
+..
+    Copyright 2014 Modelling, Simulation and Design Lab (MSDL) at 
+    McGill University and the University of Antwerp (http://msdl.cs.mcgill.ca/)
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+Static Allocator
+================
+
+Assigning locations directly within the model might be tedious or even impossible in some situations.
+In some other cases, the number of nodes might be variable, thus requiring more code in the model itself to determine the correct location.
+To solve these problems, an allocator can be defined.
+
+This section will handle about the static allocators.
+The static signifies that they use no run-time information, in contrast to the :doc:`Dynamic Allocators <dynamicallocator>` discussed later on.
+Allocation will happen as soon as the model is direct connected.
+
+As a result of allocation, a file *locationsave.txt* is created, which contains the allocation that was found.
+In future runs, it is then possible to load from this file instead of doing the allocation process all over again.
+
+Writing a custom allocator
+--------------------------
+
+Writing an allocator is rather simple. The class has a simple method called *allocate*,
+which will return a dictionary with a model_id as its key and the node to place it on as the value.
+For the allocators, it is required that all model_ids are assigned a location, as otherwise they will not appear in the saved allocation file.
+
+The *allocate* has the following parameters:
+
+#. *models*: an iterable containing all models to allocate
+#. *edges*: **must** be ignored, as it is constantly *None*
+#. *nrnodes*: the number of nodes to allocate over
+#. *totalActivities*: **must** be ignored, as it is constantly *None*
+
+Furthermore, a method *getTerminationTime* is also required, but it should always return 0 for a static allocator.
+
+This gives the following template::
+
+    class MyAllocator():
+        def allocate(self, models, edges, nrnodes, totalActivities):
+            # Do NOT use the edges and totalActivities arguments
+            # To allocate model_ids 0, 1 and 2 to node 0 and model_id 3 to node 1
+            return {0: 0, 1: 0, 2: 0, 3: 1}
+
+        def getTerminationTime(self):
+            return 0
+
+Using the allocator
+-------------------
+
+Using the static allocator that is provided in the PyPDEVS distribution is as simple as calling::
+
+    sim = Simulator(Model())
+    sim.setAutoAllocation()
+    sim.simulate()
+
+Running a custom allocator uses the same methodology as a custom scheduler.
+For the allocator with classname *MyAllocator*, in the file *myAllocator*, the configuration is as follows::
+
+    sim = Simulator(Model())
+    sim.setInitialAllocator("myAllocator", "MyAllocator")
+    sim.simulate()