V0.2 update

.github/linters/tox.ini

@@ -19,6 +19,7 @@ exclude =
     .github,
     scripts,
     tests,
+    maro/backends/*.cpp
     setup.py
 
 max-line-length = 120

.github/workflows/build_wheel.yml

@@ -34,7 +34,8 @@ jobs:
 
     - name: Compile cython files
       run: |
-        cython ./maro/backends/backend.pyx ./maro/backends/np_backend.pyx ./maro/backends/raw_backend.pyx ./maro/backends/frame.pyx -3 -E FRAME_BACKEND=NUMPY,NODES_MEMORY_LAYOUT=ONE_BLOCK -X embedsignature=True
+        python ./scripts/code_gen.py
+        cython ./maro/backends/backend.pyx ./maro/backends/np_backend.pyx ./maro/backends/raw_backend.pyx ./maro/backends/frame.pyx --cplus -3 -E NODES_MEMORY_LAYOUT=ONE_BLOCK -X embedsignature=True
 
     - name: Build wheel on Windows and macOS
       if: runner.os == 'Windows' || runner.os == 'macOS'

.github/workflows/deploy_docker_image.yml

@@ -29,7 +29,8 @@ jobs:
     - name: Build image
       run: |
         pip install -r ./maro/requirements.build.txt
-        cython ./maro/backends/backend.pyx ./maro/backends/np_backend.pyx ./maro/backends/raw_backend.pyx ./maro/backends/frame.pyx -3 -E FRAME_BACKEND=NUMPY,NODES_MEMORY_LAYOUT=ONE_BLOCK -X embedsignature=True
+        python ./scripts/code_gen.py
+        cython ./maro/backends/backend.pyx ./maro/backends/np_backend.pyx ./maro/backends/raw_backend.pyx ./maro/backends/frame.pyx --cplus -3 -E NODES_MEMORY_LAYOUT=ONE_BLOCK -X embedsignature=True
         cat ./maro/__misc__.py | grep __version__ | egrep -o [0-9].[0-9].[0-9,a-z]+ | { read version; docker build -f ./docker_files/cpu.play.df . -t ${{ secrets.DOCKER_HUB_USERNAME }}/maro:cpu -t ${{ secrets.DOCKER_HUB_USERNAME }}/maro:latest -t ${{ secrets.DOCKER_HUB_USERNAME }}/maro:cpu-$version; }
 
     - name: Login docker hub

.github/workflows/deploy_gh_pages.yml

@@ -32,7 +32,8 @@ jobs:
 
     - name: Compile cython files
       run: |
-        cython ./maro/backends/backend.pyx ./maro/backends/np_backend.pyx ./maro/backends/raw_backend.pyx ./maro/backends/frame.pyx -3 -E FRAME_BACKEND=NUMPY,NODES_MEMORY_LAYOUT=ONE_BLOCK -X embedsignature=True
+        python ./scripts/code_gen.py
+        cython ./maro/backends/backend.pyx ./maro/backends/np_backend.pyx ./maro/backends/raw_backend.pyx ./maro/backends/frame.pyx --cplus -3 -E NODES_MEMORY_LAYOUT=ONE_BLOCK -X embedsignature=True
 
     - name: Build maro inplace
       run: |

.github/workflows/test.yml

@@ -30,7 +30,8 @@ jobs:
 
     - name: Compile cython files
       run: |
-        cython ./maro/backends/backend.pyx ./maro/backends/np_backend.pyx ./maro/backends/raw_backend.pyx ./maro/backends/frame.pyx -3 -E FRAME_BACKEND=NUMPY,NODES_MEMORY_LAYOUT=ONE_BLOCK -X embedsignature=True
+        python ./scripts/code_gen.py
+        cython ./maro/backends/backend.pyx ./maro/backends/np_backend.pyx ./maro/backends/raw_backend.pyx ./maro/backends/frame.pyx --cplus -3 -E NODES_MEMORY_LAYOUT=ONE_BLOCK -X embedsignature=True
 
     - name: Build maro inplace
       run: |

docs/source/key_components/data_model.rst

@@ -8,6 +8,14 @@ the backend language for improving the execution reference. What's more,
 the backend store is a pluggable design, user can choose different backend
 implementation based on their real performance requirement and device limitation.
 
+Currenty there are two data model backend implementation: static and dynamic.
+Static implementation used Numpy as its data store, do not support dynamic
+attribute length, the advance of this version is that its memory size is same as its
+declaration.
+Dynamic implementation is hand-craft c++.
+It supports dynamic attribute (list) which will take more memory than the static implementation
+but is faster for querying snapshot states and accessing attributes.
+
 Key Concepts
 ------------
 
@@ -28,6 +36,12 @@ As shown in the figure above, there are some key concepts in the data model:
   The ``slot`` number can indicate the attribute values (e.g. the three different
   container types in CIM scenario) or the detailed categories (e.g. the ten specific
   products in the `Use Case <#use-case>`_ below). By default, the ``slot`` value is one.
+  As for the dynamic backend implementation, an attribute can be marked as is_list or is_const to identify
+  it is a list attribute or a const attribute respectively.
+  A list attribute's default slot number is 0, and can be increased as demand, max number is 2^32.
+  A const attribute is designed for the value that will not change after initialization,
+  e.g. the capacity of a port/station. The value is shared between frames and will not be copied
+  when taking a snapshot.
 * **Frame** is the collection of all nodes in the environment. The historical frames
   present the aggregated state of the environment during a specific period, while
   the current frame hosts the latest state of the environment at the current time point.
@@ -41,6 +55,7 @@ Use Case
 
   .. code-block:: python
 
+    from maro.backends.backend import AttributeType
     from maro.backends.frame import node, NodeAttribute, NodeBase, FrameNode, FrameBase
 
     TOTAL_PRODUCT_CATEGORIES = 10
@@ -51,8 +66,8 @@ Use Case
 
     @node("warehouse")
     class Warehouse(NodeBase):
-        inventories = NodeAttribute("i", TOTAL_PRODUCT_CATEGORIES)
-        shortages = NodeAttribute("i", TOTAL_PRODUCT_CATEGORIES)
+        inventories = NodeAttribute(AttributeType.Int, TOTAL_PRODUCT_CATEGORIES)
+        shortages = NodeAttribute(AttributeType.Int, TOTAL_PRODUCT_CATEGORIES)
 
         def __init__(self):
             self._init_inventories = [100 * (i + 1) for i in range(TOTAL_PRODUCT_CATEGORIES)]
@@ -65,9 +80,9 @@ Use Case
 
     @node("store")
     class Store(NodeBase):
-        inventories = NodeAttribute("i", TOTAL_PRODUCT_CATEGORIES)
-        shortages = NodeAttribute("i", TOTAL_PRODUCT_CATEGORIES)
-        sales = NodeAttribute("i", TOTAL_PRODUCT_CATEGORIES)
+        inventories = NodeAttribute(AttributeType.Int, TOTAL_PRODUCT_CATEGORIES)
+        shortages = NodeAttribute(AttributeType.Int, TOTAL_PRODUCT_CATEGORIES)
+        sales = NodeAttribute(AttributeType.Int, TOTAL_PRODUCT_CATEGORIES)
 
         def __init__(self):
             self._init_inventories = [10 * (i + 1) for i in range(TOTAL_PRODUCT_CATEGORIES)]
@@ -86,7 +101,8 @@ Use Case
 
         def __init__(self):
             # If your actual frame number was more than the total snapshot number, the old snapshots would be rolling replaced.
-            super().__init__(enable_snapshot=True, total_snapshot=TOTAL_SNAPSHOT)
+            # You can select a backend implementation that will fit your requirement.
+            super().__init__(enable_snapshot=True, total_snapshot=TOTAL_SNAPSHOT, backend_name="static/dynamic")
 
 * The operations on the retail frame.
 
@@ -139,19 +155,34 @@ All supported data types for the attribute of the node:
    * - Attribute Data Type
      - C Type
      - Range
-   * - i2
-     - int16_t
+   * - Attribute.Byte
+     - char
+     - -128 .. 127
+   * - Attribute.UByte
+     - unsigned char
+     - 0 .. 255
+   * - Attribute.Short (i2)
+     - short
      - -32,768 .. 32,767
-   * - i, i4
+   * - Attribute.UShort
+     - unsigned short
+     - 0 .. 65,535
+   * - Attribute.Int (i4)
      - int32_t
      - -2,147,483,648 .. 2,147,483,647
-   * - i8
+   * - Attribute.UInt (i4)
+     - uint32_t
+     - 0 .. 4,294,967,295
+   * - Attribute.Long (i8)
      - int64_t
      - -9,223,372,036,854,775,808 .. 9,223,372,036,854,775,807
-   * - f
+   * - Attribute.ULong (i8)
+     - uint64_t
+     - 0 .. 18,446,744,073,709,551,615
+   * - Attribute.Float (f)
      - float
      - -3.4E38 .. 3.4E38
-   * - d
+   * - Attribute.Double (d)
      - double
      - -1.7E308 .. 1.7E308
 
@@ -216,3 +247,15 @@ For better data access, we also provide some advanced features, including:
 
     # Query attribute by frame index list.
     states = test_nodes_snapshots[[0, 1, 2]: 0: "int_attribute"]
+
+    # The querying states is different between static and dynamic implementation
+    # Static implementation will return a 1-dim numpy array, as the shape is known according to the parameters.
+    # Dynamic implementation will return a 4-dim numpy array, that shape is (ticks, node_indices, attributes, slots).
+    # Usually we can just flatten the state from dynamic implementation, then it will be same as static implementation,
+    # except for list attributes.
+    # List attribute only support one tick, one node index and one attribute name to query, cannot mix with normal attributes
+    states = test_nodes_snapshots[0: 0: "list_attribute"]
+
+    # Also with dynamic implementation, we can get the const attributes which is shared between snapshot list, even without
+    # any snapshot (need to provided one tick for padding).
+    states = test_nodes_snapshots[0: [0, 1]: ["const_attribute", "const_attribute_2"]]

docs/source/key_components/rl_toolkit.rst

@@ -63,19 +63,19 @@ Learner and Actor
 Scheduler
 ---------
 
-A ``Scheduler`` is the driver of an episodic learning process. The learner uses the scheduler to repeat the 
-rollout-training cycle a set number of episodes. For algorithms that require explicit exploration (e.g., 
+A ``Scheduler`` is the driver of an episodic learning process. The learner uses the scheduler to repeat the
+rollout-training cycle a set number of episodes. For algorithms that require explicit exploration (e.g.,
 DQN and DDPG), there are two types of schedules that a learner may follow:
 
-* Static schedule, where the exploration parameters are generated using a pre-defined function of episode 
-  number. See ``LinearParameterScheduler`` and ``TwoPhaseLinearParameterScheduler`` provided in the toolkit 
-  for example. 
+* Static schedule, where the exploration parameters are generated using a pre-defined function of episode
+  number. See ``LinearParameterScheduler`` and ``TwoPhaseLinearParameterScheduler`` provided in the toolkit
+  for example.
 * Dynamic schedule, where the exploration parameters for the next episode are determined based on the performance
   history. Such a mechanism is possible in our abstraction because the scheduler provides a ``record_performance``
-  interface that allows it to keep track of roll-out performances. 
+  interface that allows it to keep track of roll-out performances.
 
-Optionally, an early stopping checker may be registered if one wishes to terminate training when certain performance 
-requirements are satisfied, possibly before reaching the prescribed number of episodes.   
+Optionally, an early stopping checker may be registered if one wishes to terminate training when certain performance
+requirements are satisfied, possibly before reaching the prescribed number of episodes.
 
 Agent Manager
 -------------
@@ -125,11 +125,11 @@ scenario agnostic.
 Algorithm
 ---------
 
-The algorithm is the kernel abstraction of the RL formulation for a real-world problem. Our abstraction  
-decouples algorithm and model so that an algorithm can exist as an RL paradigm independent of the inner 
-workings of the models it uses to generate actions or estimate values. For example, the actor-critic 
+The algorithm is the kernel abstraction of the RL formulation for a real-world problem. Our abstraction
+decouples algorithm and model so that an algorithm can exist as an RL paradigm independent of the inner
+workings of the models it uses to generate actions or estimate values. For example, the actor-critic
 algorithm does not need to concern itself with the structures and optimizing schemes of the actor and
-critic models. This decoupling is achieved by the ``LearningModel`` abstraction described below.   
+critic models. This decoupling is achieved by the ``LearningModel`` abstraction described below.
 
 
 .. image:: ../images/rl/algorithm.svg
@@ -153,18 +153,18 @@ Block, NNStack and LearningModel
 --------------------------------
 
 MARO provides an abstraction for the underlying models used by agents to form policies and estimate values.
-The abstraction consists of a 3-level hierachy formed by ``AbsBlock``, ``NNStack`` and ``LearningModel`` from 
+The abstraction consists of a 3-level hierachy formed by ``AbsBlock``, ``NNStack`` and ``LearningModel`` from
 the bottom up, all of which subclass torch's nn.Module. An ``AbsBlock`` is the smallest structural
-unit of an NN-based model. For instance, the ``FullyConnectedBlock`` provided in the toolkit represents a stack 
-of fully connected layers with features like batch normalization, drop-out and skip connection. An ``NNStack`` is 
-a composite network that consists of one or more such blocks, each with its own set of network features. 
-The complete model as used directly by an ``Algorithm`` is represented by a ``LearningModel``, which consists of 
-one or more task stacks as "heads" and an optional shared stack at the bottom (which serves to produce representations 
-as input to all task stacks). It also contains one or more optimizers responsible for applying gradient steps to the 
-trainable parameters within each stack, which is the smallest trainable unit from the perspective of a ``LearningModel``. 
-The assignment of optimizers is flexible: it is possible to freeze certain stacks while optimizing others. Such an 
-abstraction presents a unified interface to the algorithm, regardless of how many individual models it requires and how 
-complex the model architecture might be.  
+unit of an NN-based model. For instance, the ``FullyConnectedBlock`` provided in the toolkit represents a stack
+of fully connected layers with features like batch normalization, drop-out and skip connection. An ``NNStack`` is
+a composite network that consists of one or more such blocks, each with its own set of network features.
+The complete model as used directly by an ``Algorithm`` is represented by a ``LearningModel``, which consists of
+one or more task stacks as "heads" and an optional shared stack at the bottom (which serves to produce representations
+as input to all task stacks). It also contains one or more optimizers responsible for applying gradient steps to the
+trainable parameters within each stack, which is the smallest trainable unit from the perspective of a ``LearningModel``.
+The assignment of optimizers is flexible: it is possible to freeze certain stacks while optimizing others. Such an
+abstraction presents a unified interface to the algorithm, regardless of how many individual models it requires and how
+complex the model architecture might be.
 
 .. image:: ../images/rl/learning_model.svg
    :target: ../images/rl/learning_model.svg
@@ -196,11 +196,11 @@ And performing one gradient step is simply:
 Explorer
 -------
 
-MARO provides an abstraction for exploration in RL. Some RL algorithms such as DQN and DDPG require 
-explicit exploration, the extent of which is usually determined by a set of parameters whose values 
+MARO provides an abstraction for exploration in RL. Some RL algorithms such as DQN and DDPG require
+explicit exploration, the extent of which is usually determined by a set of parameters whose values
 are generated by the scheduler. The ``AbsExplorer`` class is designed to cater to these needs. Simple
-exploration schemes, such as ``EpsilonGreedyExplorer`` for discrete action space and ``UniformNoiseExplorer`` 
-and ``GaussianNoiseExplorer`` for continuous action space, are provided in the toolkit. 
+exploration schemes, such as ``EpsilonGreedyExplorer`` for discrete action space and ``UniformNoiseExplorer``
+and ``GaussianNoiseExplorer`` for continuous action space, are provided in the toolkit.
 
 As an example, the exploration for DQN may be carried out with the aid of an ``EpsilonGreedyExplorer``: