.. _org-mode:

#################
Organizing models
#################

Code structuring and refactoring concepts illustrated on the "vehicule suspension"
example. Indeed, in the previous sessions, we have created two models for the
suspension. First an equation based model (ODE), then a model based on the acausal
connection of physical components from the Modelica Standard Library.

1. Inheritance: extending models with subclassing
2. Packages: structuring a set of models

.. TODO : reformulate this to include also *composition*. Illustrate with a car


Inheritance: extending models with subclassing
==============================================

Objective: **avoid repetition**, as expressed in the `DRY (Don't Repeat Yourself) principle`_.

Modelica keyword: ``extend``

Ressources: Michael Tiller's online book *"Modelica by Example"* [Tiller-2014]_,
"Basic Equations" chapter:

* `Example "Lotka-Volterra Systems"`_
* `Review "Model Definition"`_

For this exercise on inheritance, you can use your own code from the previous sessions,
but if there is a problem, here are two fresh models.
You can observe that many declarations are duplicated, especially the parameters.

.. literalinclude:: ./examples/10 Suspension/suspensionODE.mo

.. literalinclude:: ./examples/10 Suspension/suspensionComponents.mo

.. admonition:: Exercise
    :class: attention

    Refactor these two suspension models so that they inherit from one ``PartialSuspension``


.. admonition:: Bonus Exercise
    :class: attention

    Open the ``Resistor``, ``Capacitor`` and ``Inductor``  model of the
    ``Modelica.Electrical.Analog.Basic`` library.
    
    Create a class diagram showing these models along with their parent classes. 


**A small usability problem**: if you close OMEdit and reopen one of refactored models
which inherits from the abstract model, you'll get errors because it cannot be found::

    [2] 17:42:43 Translation Error
    [suspensionComponents: 2:3-2:29]: Base class suspensionAbstract not found in scope suspensionComponents.

(also the icon is a red crossed square).

We need to tell OpenModelica that these models “live in the same building”.
→ this is exactly the purpose of package…


.. _org-pack:

Packages: structuring a set of models
=====================================

A Modelica :term:`package` (like in Python) is a way to store together a coherent
set of models (a library).
As an example taken from a workshop rather than the programming world,
models for a *Hammer* and a *Screwdriver* could be stored in a package named *Toolbox*.

Package creation on OMEdit
--------------------------

Step 1, package creation :numref:`OME_Package_new`:
Create a new model named ``Toolbox``,
but select the model “Specialization” to ``Package``
(rather than the default choice ``Model``).

Important: uncheck the default choice “Save contents in one file”.

.. figure:: ./screenshots/OMEdit_Package_new.png
    :height: 20 em
    :name: OME_Package_new

    Creation of a ``Package`` named ``Toolbox``, to be saved in multiple files

Now save the package and observe the result with a file browser.

Step 2, model creation within the package (:numref:`OME_Package_Model`):
In the Libraries Brower, right-click the package to create a new model ``Hammer`` from the context menu of the package.
Observe that the “Insert in class” option is set to ``Toolbox``.

.. figure:: ./screenshots/OMEdit_Package_Model_within.png
    :height: 20 em
    :name: OME_Package_Model

    Creation of a ``Model`` named ``Hammer`` within the existing ``Toolbox`` package

Again, observe the result in a file brower. Also notice the first line of the ``Hammer`` model.

.. admonition:: Question
    :class: attention
    
    Summarize the file structure of a Modelica package in a diagram
    showing the layout of the files and the key syntax elements in those files.
    
    In particular, how many times is the package name ``Toolbox`` used?


Refactoring existing code in a package
--------------------------------------

Now that you have seen how a package is created from scratch, let's use this
knowlegde on existing models. This probably requires making some edits *outside OMEdit*,
typically in a text editor like `Notepad++`_.
This is because during the modification process, some files are temporarily
invalid Modelica.

.. admonition:: Exercise
    :class: attention

    Refactor the three suspension models so that they are in one package
    ``SuspensionPackage``.


Bonus for Packages
------------------

Look at the ``Modelica.Electrical.Analog`` package to see how it extends
from ``Modelica.Icons.Package``. Use the same trick to get a nice icon for your package.
Then you can customize it in the Icon View.


.. _DRY (Don't Repeat Yourself) principle: https://web.archive.org/web/20170813084933/http://programmer.97things.oreilly.com/wiki/index.php/Don't_Repeat_Yourself
.. _Example "Lotka-Volterra Systems": https://mbe.modelica.university/behavior/equations/population/
.. _Review "Model Definition": https://mbe.modelica.university/behavior/equations/model_def/
.. _Notepad++: https://notepad-plus-plus.org/

.. NB if the O'Reilly link is broken, I've saved a copy in biblio/DRY principle.md