.. _use-comp:

###############################
Physical components in Modelica
###############################


.. admonition:: Learning objectives
    :class: note
    
    In this session, you'll learn about **physical components**:
    what they are, how to connect them?
    These components are the main building blocks of most Modelica models.


Main ressources needed:

* Michael Tiller's online book *"Modelica by Example"* [Tiller-2014]_, second part "Object-Oriented Modeling":

    * chapter `Connectors`_
    * chapter `Components`_


Connecting physical components
==============================

We start by considering an electrical system, since the representation
of these systems in Modelica will fully reminds us of the usual representation
on paper.

In OpenModelica's Diagram View, drag and drop components from the ``Modelica.Electrical``
(a subpackage of Modelica Standard Library) to create the simple RLC circuit of :numref:`elec_connect`:


.. figure:: ./examples/elec_connect_annot.png
    :width: 30 em
    :name: elec_connect

    connection of a few electrical components from the ``Modelica.Electrical`` standard package

Now switch to Text View and look for a set of lines starting
with a keyword, ``connect``::

    equation
      connect(constantVoltage1.p, inductor1.p) annotation(/*[...]*/)
      connect(capacitor1.p, inductor1.n) annotation(/*[...]*/)
      /*[...]*/


.. admonition:: Question
    :class: attention

    What is the relation between each of these lines to each electrical node?
    
    Bonus: for one ``connect(...)`` line of you choice, you can fiddle with
    the :term:`annotation` which describes of the connection line is drawn.
    For example, you can replace the color attribute ``color = {0, 0, 255}``
    by ``color = {255, 0, 0}`` and jump to the diagram view to see the result.


.. admonition:: Theoretical Exercise
    :class: attention

    Using your knowledge of electrical circuits, what *physical equations*
    correspond to the *connection of components*, at each node?
    
    In particular, for the node 2 on :numref:`elec_connect`, list the *set of equations*
    which are equivalent to the connection of ``inductor1.n``, ``capacitor1.p``
    and ``resistor1.p``.
    
    In the general case, when connecting :math:`n` ports, how many equations are there?



.. _use-comp-vehic:

Vehicle suspension with components
==================================

Now use components from ``Modelica.Mechanics.Translational`` to recreate
the ODE model of a simplified Vehicle suspension.

Using the same parameters for mass, spring constant and damping, check that
both models yields the same result.

Now, as with electrical circuit, what *physical equations
correspond to the connection of components*?


Acausal connection
==================

In Modelica, the connection of components is a generalized notion
of the connection of electrical components in an electrical diagram.

Physical variables can be classified into:

* potential (or across) variables
* flow (or through) variables

Also, the ``connect`` equations corresponds to classical physical laws

* potential equation: electrical wires are equipotential (no wire resistance)
* flow equation: charge conservation at an electrical node

Now, you  fill this table with variables and classical laws of the most usual domains:

=========================  ==================  =============  ===================  ===================
Domain                     Potential variable  Flow variable  Potential equation   Flow equation
=========================  ==================  =============  ===================  ===================
electricity                voltage (V)         current (A)    equipotential wires  charge conservation
mechanics, 1D translation
mechanics, 1D rotation
thermal transfers
1D fluid mechanics
=========================  ==================  =============  ===================  ===================


.. _Connectors: https://mbe.modelica.university/components/connectors/
.. _Components: https://mbe.modelica.university/components/components/