.. _market-calibration-areas-label:

========================
Market Calibration Areas
========================

Market calibration areas (samkjøringsområder) is used to group
busbars into greater areas.

.. toctree::
    :titlesonly:

Motivating example:
===================

.. mermaid::

    flowchart LR
        subgraph MarketArea1
            numedal("Numedal")
        end
        subgraph MarketArea2
            otta("Otta")
        end

        numedal -. "⚡dc⚡" .- otta

``Numedal`` belongs to area ``MarketArea1``.
``Otta`` belongs to ``MarketArea2``.

``Numedal`` and ``Otta`` are connected with a DC-line.

This JSON example represents the above model,
where certain non-relevant, but required parts are cut for clarity:

.. code-block:: json
    :linenos:

    {
        "model": {
            "market_calibration_areas": [
                {
                    "name": "market_area_1"
                },
                {
                    "name": "market_area_2"
                }
            ],
            "busbars": [
                {
                    "name": "numedal"
                },
                {
                    "name": "otta"
                }
            ],
            "dclines": [
                {
                    "name": "DC_A"
                }
            ],
            "connections": [
                {
                    "from": "numedal",
                    "to": "DC_A"
                },
                {
                    "from": "DC_A",
                    "to": "otta"
                },
                {
                    "from": "numedal",
                    "to": "market_area_1"
                },
                {
                    "from": "otta",
                    "to": "market_area_2"
                }
            ]
        }
    }

Multiple busbars:
=================

To expand on the example above, to have multiple busbars per area, connect
the busbar object to the market calibration area.

.. mermaid::

    flowchart LR
        subgraph MarketArea1
            numedal("Numedal")
            rjukan("Rjukan")
            ustaoset("Ustaoset")
        end
        subgraph MarketArea2
            otta("Otta")
            nordherad("Nordherad")
            litldalen("Litldalen")
        end

        numedal -. "⚡dc1⚡" .- otta
        rjukan -. "⚡" .- numedal
        ustaoset -. "⚡" .- numedal

        nordherad -. "⚡" .- otta
        litldalen -. "⚡" .- otta


Full JSON source listing:
-------------------------

.. collapse:: Expand to see full JSON listing with 2 market calibration areas and 6 busbars.

    .. literalinclude:: ../../../tests/market_calibration_areas.json
      :language: JSON
      :linenos:

Example code:
-------------

.. literalinclude:: ../../../tests/market_calibration_areas.py
    :language: Python
    :linenos: