drawio2py/docs/_build/html/_sources/formalisms/CBD.rst.txt

CBD Formalism
=============

Causal Block Diagrams allow for finding solutions to mathematical problems.

Setting up Drawio
------------------
In drawio, select :menuselection:`File --> Open Library` and load :file:`CBDLibrary.xml`
(which can be found :download:`here <../../formalisms/CBD/CBDLibrary.xml>`).
This provides a set of primitive CBD blocks that can be used in your models.
Once included, it can be found at the top of the shapes library.

.. rst-class:: table-center

+------------------------------------------+
| .. figure:: ../_figures/library.png      |
|                                          |
|   CBD Library in the Sidebar             |
+------------------------------------------+

.. _block-props:

Block Properties
----------------
All blocks in the library have some block-specific properties that can be set by the user.
Hovering over a component shows all non-empty properties that were set on this shape.

There are several ways of accessing/modifying these properties:

* Double Click with the left mouse button on a shape.
* Click with right mouse button to open a shape's context menu.
  Near the bottom of the list, select :menuselection:`Edit Data`.
* Select the shape (left mouse button) and in the top of the right panel,
  go to :menuselection:`Arrange --> Edit Data`.
* Select the shape and press :kbd:`CTRL + M` or :kbd:`CMND + M`.

.. warning:: Do not change the :code:`class_name` as the converter relies on this property.

.. rst-class:: table-center

+------------------------------------------+
| .. figure:: ../_figures/properties.png   |
|                                          |
|   Example of the Property Window (for a  |
|   ConstantBlock)                         |
+------------------------------------------+


.. _library:

Working with Library Blocks
---------------------------
To guarantee a consistent visual appearance of CBD models,
no blocks in the library, except for the Custom Block, can be resized.
Every block has zero or more input and output ports. Input ports are represented by
the :code:`InputPortBlock` (black triangle) and output ports by the :code:`OutputPortBlock`
(white triangle). When selecting (left mouse button) a port, a small, movable,
yellow/orange diamond-shaped anchor will appear in front of the port's name.
The position of this label can be changed by dragging the anchor.
The port name can be altered in the :menuselection:`Edit Data` window.

.. For each of a CBD model's top-level :code:`OutputPortBlock` shapes, a :code:`signal` property
    may be added (see :ref:`block-props`).
    The :code:`drawio2cbd` will then generate code to produce a plot, using https://bokeh.org/.
    Note that bokeh produces an HTML document which is rendered in a browser
    and allows some user interaction with the plot.
    The value of the :code:`signal` property on a top-level :code:`OutputPortBlock` should be the title
    to be put on the plot. Multiple signals may be rendered onto the same plot.
    For more complex CBD simulation result analysis and visualization, code should be added
    at the bottom of the generated file.

Each CBD block that is *not* a port may have the following properties:

* :code:`ID` or :code:`id`: The drawio unique ID for this block. Note that drawio automatically
  overwrites a property with the key :code:`id` by the value shown by :code:`ID` (upon saving the diagram).
* :code:`block_name`: The name of the block. It is required that
  all blocks have a unique name within a class. When omitted, the :code:`ID` is used.
* :code:`class_name`: The type of block.

  .. warning:: Do not change the :code:`class_name` as the converter relies on this property.
               Changing it makes it so the block type changes as well in the simulation.

* :code:`symbol`: The block symbol that must be rendered by MathJax/LaTeX. This is a purely
  graphical attribute and is ignored by the script.

Optionally, additional class parameters can be provided by adding more properties.
Their values will be passed on as default values for the corresponding property as an argument, e.g., to
use strings, enclose the value in "..." or '...', for :code:`None`, leave it empty or litterally type
":code:`None`"...

.. warning:: Make sure these values are expressions/rvalues! If not, the generated Python file will crash,
              or cause some unexpected behavior. Furthermore, newlines may not be used in these values.

Class parameters that cannot be used are: :code:`label` (prevented by drawio), :code:`id` (overwritten by
drawio), :code:`placeholders` (prevented by drawio), :code:`symbol` (ignored by the converter)
and :code:`__docstring__` (used for other purposes, see later).

.. note:: Blocks with a variable number of inputs (i.e., the :code:`OrBlock` and the
          :code:`AndBlock`) may still need additional ports to be placed/removed.


.. _custom-block:

Creating Custom CBD Blocks
-------------------------------
A custom hierarchical CBD block is constructed as a network of already provided blocks
(which in their own right may be custom hierarchical blocks)
using the :code:`Custom Block` element from :file:`CBDLibrary.xml`.
This is a collapsible component in which a block diagram may be drawn.
It has two important properties:

* :code:`class_name`: The new class name for the custom block. Note that all class names must be unique!
* :code:`block_name`: The name of an instance of the CBD model if it's the top-level CBD.

Additional properties can be added to create custom class parameters.
The same set of parameters that was discussed above cannot be set,
with the exception of :code:`__docstring__`, which now allows adding documentation to custom blocks.

The empty rectangle is a container for the custom hierachical block.
Blocks can be dragged into the rectangular area and connected.
:code:`InputPortBlock` and :code:`OutputPortBlock` are used to add inputs and outputs with
their :code:`name` property set to the port's name.

.. hint:: The :code:`Custom Block` component can, in constrast with all other blocks in the
          library, be resized. This allows for larger hierarchical models to be created, as the
          basic blocks cannot be resized.

.. rst-class:: table-center

+------------------------------------------+
| .. figure:: ../_figures/custom-block.png |
|                                          |
|   Custom Sine Generator Block with no    |
|   Input Ports, a single Output Port and  |
|   a Custom Graphical Representation      |
+------------------------------------------+

Next, create a graphical representation of the block (i.e., what an instance
block should look like when used in a block diagram), add the corresponding
ports and set the property :code:`class_name` to the same class as that set in the
:code:`Custom Block`. Make sure not to forget to add any class parameters that were
added to the :code:`Custom Block`.

.. hint:: This can be done easily by adding a predefined block and changing its
          ports and properties to match the new custom block.

.. note:: Only the :code:`Custom Block` components will be read by the converter.
          Anything else is implicitly ignored. Furthermore, the script is page-independent,
          meaning multiple pages may be used inside a single drawio document to maintain a
          clean overview of the created models.

Conversion
----------
To generate code from the created drawio files, execute the script with the :code:`-F CBD` flag.
This tells :code:`DrawioConvert` to use the CBD formalism. Two files will be created:

* :code:`model.py`: The model file, containing the code for the modelled blocks.
* :code:`experiment.py`: The "protected" experiment file. You can feely add/remove parts of this file
  without fear of it being overwritten next execution. Use the :code:`-f`/:code:`--force` flag to
  force overwrite the file.

It is possible to use continuous models, where they are discretized to a certain delta. This is
customizeable using the :code:`-E`/:code:`--environment` flag. I.e. by setting :code:`-E delta=0.1`,
it is possible to execute in steps of 0.1 time-units. Note how :code:`-t`/:code:`--time` identifies
the total simulation time, **not** the amount of steps taken.