.. _mod_topology:

====================================
Working with the bus/branch topology
====================================

.. currentmodule:: cim2busbranch.topology

Cim2BusBranch does not create PYPOWER cases directly, but uses :class:`Bus`,
:class:`Branch` and :class:`Generator` objects contained within a
:class:`Topology` as an intermediary step.

The original intention for this is as follows: Usually, you want to perform
more than one load flow calculation on the same topology. Some attributes may
be static (like branch resistances) while other may dynamically vary between
two calculations. Cim2BusBranch allows you to keep the static values parsed
from the CIM file and to modify some attributes with dynamic values (e.g. from
external simulations or CSV files) before each load flow calculation.

An additional advantage is, that it doesn't set Cim2BusBranch at PYPOWER. Thus,
input for other load flow tools could easily be created from a
:class:`Topology` object.

This is how these dynamic attributes work:

    >>> bus = Bus(p=2, q=1)
    >>> bus.p
    2
    >>> bus.p += 2
    >>> bus.p
    4
    >>> bus.p_static
    2
    >>> bus.p_static = 3
    Error
    >>> bus.reset()
    >>> bus.p
    2

You can also get a :func:`~collections.namedtuple` with the current values of
all dynamic attributes from a bus, branch or generator:

    >>> bus.attributes()
    BusAttr(p=2, q=1)

You may have noticed that this tuple equates to the array *PYPOWER* expects as
a bus description.


Attributes of :class:`Bus`
==========================

Dynamic attributes:

#. ``name``: Bus name (*string*)
#. ``type``: Bus type (One of these attributes of :obj:`bus_type`: *PQ*, *PV*,
   *REF*, *ISOLATED*)

1. bus number (positive integer)
2. bus type
- PQ bus = 1
- PV bus = 2
- reference bus = 3
- isolated bus = 4
3. C{Pd}, real power demand (MW)
4. C{Qd}, reactive power demand (MVAr)
5. C{Gs}, shunt conductance (MW demanded at V = 1.0 p.u.)
6. C{Bs}, shunt susceptance (MVAr injected at V = 1.0 p.u.)
7. area number, (positive integer)
8. C{Vm}, voltage magnitude (p.u.)
9. C{Va}, voltage angle (degrees)
10. C{baseKV}, base voltage (kV)
11. C{zone}, loss zone (positive integer)
12. C{maxVm}, maximum voltage magnitude (p.u.)
13. C{minVm}, minimum voltage magnitude (p.u.)
