v0.3.0 - Mayer's Merit (May, 21, 2020)
++++++++++++++++++++++++++++++++++++++

TESPy version 0.3.0 -
`Mayer's Merit <https://en.wikipedia.org/wiki/Julius_von_Mayer>`_ comes with a
lot of new features and a publication in the Journal of Open Source Software.
The paper is available at the website of the
`JOSS <https://joss.theoj.org/papers/590b0b4767606bce4d0ebe397d4b7a4f>`_.

BibTeX citation::

    @article{Witte2020,
        doi = {10.21105/joss.02178}
        year = {2020},
        publisher = {The Open Journal},
        volume = {5},
        number = {49},
        pages = {2178},
        author = {Francesco Witte and Ilja Tuschy},
        title = {{TESPy}: {T}hermal {E}ngineering {S}ystems in {P}ython},
        journal = {Journal of Open Source Software}
    }

New Features
############
- Make entropy :code:`myconn.s.val` or :code:`myconn.s.val_SI` and specific
  volume :code:`myconn.vol.val` or :code:`myconn.vol.val_SI` respectively
  available after simulation
  (`PR #172 <https://github.com/oemof/tespy/pull/172>`_).
- Connections, components and busses are now easily accessible on every
  network. Connections now have a label, which can be specified individually,
  the default value of the label is given by the following logic.
  :code:`source:source_id_target:target_id`, where source and target are the
  labels of the connected components.

  Access the objects with:

  - mynetwork.busses['mybuslabel']
  - mynetwork.components['mycomponentlabel']
  - mynetwork.connections['myconnectionlabel']

  (`PR #173 <https://github.com/oemof/tespy/pull/173>`_)
- Specification of the CoolProp back end is now possible. You can specify the
  back end by adding it in front of the fluid's name on creating a network, for
  example:

  .. code-block:: python

      from tespy.networks import network
      fluid_list = ['air', 'BICUBIC::water', 'INCOMP::DowQ']
      network(fluids=fluid_list)

  If you do not specify a back end :code:`HEOS` will be applied (as for
  :code:`air` in this example). This has been the case until now as well, thus
  no further changes are required to match an 0.2.x application to the
  0.3.x API. For all back ends available please refer to the
  :ref:`fluid properties section <tespy_fluid_properties_label>`. To specify
  the fluid vector on a connection leave out the back end specification, e.g.:

  .. code-block:: python3

      myconnection.set_attr(fluid={'DowQ': 1, 'water': 0, 'air': 0})

  (`PR #174 <https://github.com/oemof/tespy/pull/174>`_).
- Unsetting a value is now also possible using :code:`None` instead of
  :code:`np.nan` (`PR #178 <https://github.com/oemof/tespy/pull/178>`_).
- It is possible to choose a base for your components when adding them to a
  bus:

    - :code:`'component'`: This means, the efficiency definition of the bus is

      .. math::

          \eta=\frac{\dot{E}_\mathrm{bus}}{\dot{E}_\mathrm{component}}

    - :code:`'bus'`: This means, the efficiency definition of the bus is

      .. math::

          \eta=\frac{\dot{E}_\mathrm{component}}{\dot{E}_\mathrm{bus}}

  These definitions also apply to the characteristic line usage. The default
  setting (if you do not specify the base) uses :code:`'base': 'component'`.
  You therefore do not need do adapt your scripts regarding this change. For
  an example of the bus usage see the examples section below
  (`PR #157 <https://github.com/oemof/tespy/pull/157>`_).
- Within the busses' printouts the efficiency of every component on the
  respective bus is displayed. Additionally, it is possible to get the
  bus value and the efficiency of a specific component on a specific bus.

    - to get the bus value use :code:`mycomp.calc_bus_value(mybus)` and
    - to get the efficiency use :code:`mycomp.calc_bus_efficiency(mybus)`

  where :code:`mycomp` is a component object and :code:`mybus` is a bus the
  component has been added to
  (`PR #157 <https://github.com/oemof/tespy/pull/157>`_).
- New component :py:class:`tespy.components.nodes.droplet_separator` for
  separation of a single fluid in two phase state into saturated gas and
  saturated liquid phase. An example is given in the docstrings of the class
  documentation (`PR #186 <https://github.com/oemof/tespy/pull/186>`_).
- New component :py:class:`tespy.components.heat_exchangers.parabolic_trough`
  for concentrated solar power simulation. An example is given in the
  docstrings of the class documentation
  (`PR #191 <https://github.com/oemof/tespy/pull/191>`_).
- New property :code:`min_iter` of the
  :py:class:`tespy.networks.networks.network` class, allowing to specify the
  minimum amount of iterations before a solution is accepted
  (`PR #197 <https://github.com/oemof/tespy/pull/197>`_).

Documentation
#############
- Documentation has been updated according to the API-changes.
- Fixed many typos on the online-documentation.

Parameter renaming
##################
- Adding components to a bus now requires :code:`'comp'` instead of :code:`'c'`
  and :code:`'param'` instead of :code:`'p'`
  (`PR #157 <https://github.com/oemof/tespy/pull/157>`_).
- The former parameter :code:`kA` has been renamed to :code:`kA_char` as the
  behavior in offdesign was following a characteristic instead of a constant
  value. Additionally a new parameter :code:`kA` has been implemented, which
  represents a specified constant value for :code:`kA` in both design and
  offdesign cases (`PR #199 <https://github.com/oemof/tespy/pull/199>`_).

Testing
#######
- Move from nose to pytest
  (`PR #165 <https://github.com/oemof/tespy/pull/165>`_).
- Add fluid property test for a mixture of a tespy_fluid with a third
  fluid and a mixture of the same individual fluids
  (`PR #174 <https://github.com/oemof/tespy/pull/174>`_).
- Add a gasturbine model test for comparison of the stoichiometric combustion
  chamber with the standard combustion chamber
  (`PR #174 <https://github.com/oemof/tespy/pull/174>`_).
- Add bus tests for efficiency definitions
  (`PR #157 <https://github.com/oemof/tespy/pull/157>`_).
- Add Python 3.8, PEP and documentation build tests
  (`PR #201 <https://github.com/oemof/tespy/pull/201>`_).

Bug fixes
#########
- Increase the number of support points for tespy_fluid tabular data creation
  in order to lift accuracy to a more acceptable value
  (`PR #174 <https://github.com/oemof/tespy/pull/174>`_).
- Fix the default characteristic line for compressor isentropic efficiency: The
  line did not have an intersection with the point 1/1
  (`PR #196 <https://github.com/oemof/tespy/pull/196>`_).
- If a temperature value of a mixture was not found within the maximum number
  of newton iterations in the :py:mod:`tespy.tools.fluid_properties` module,
  the wrong value was still displayed in the output without a warning. In this
  case, the value will be :code:`nan` in the future and a warning message is
  displayed (`PR #200 <https://github.com/oemof/tespy/pull/200>`_).

Other changes
#############
- Improve naming in networks, components and connections modules
  (`PR #172 <https://github.com/oemof/tespy/pull/172>`_,
  `PR #175 <https://github.com/oemof/tespy/pull/175>`_).
- The Parameter :code:`T_range` of networks is deprecated. The fluid property
  calls for mixtures have been modified to prevent errors when the temperature
  of the mixture is below the minimum or above the maximum temperature limit of
  a component of the mixture
  (`PR #200 <https://github.com/oemof/tespy/pull/200>`_).
- Restructure package skeleton
  (`PR #201 <https://github.com/oemof/tespy/pull/201>`_).

Changes in the API
##################
The changes affect

- reading design point information from the :code:`design_path`
- reading starting value information from the :code:`init_path`
- and loading networks with the network reader's
  :py:meth:`tespy.networks.network_reader.load_network` method.

Data generated in older versions of TESPy can not be imported. In order to fix
this follow the steps below.

- rename the :code:`comps` folder to :code:`components`
- rename the :code:`conns.csv` file to :code:`connections.csv`

and within the file rename the columns

- :code:`s` to :code:`source`
- :code:`s_id` to :code:`source_id`
- :code:`t` to :code:`target`
- :code:`t_id` to :code:`target_id`

If you want to use the network reader,

- create a :code:`network.json` file.
- add the desired contents as listed below.

The fluids are represented in a dictionary containing the fluid's names as keys
and the CoolProp back end as value. :code:`"HEOS"` is the default back end,
which has been used until version 0.2.x in TESPy.

.. code-block:: json

    {
        "fluids":
        {
            "CO2": "TTSE",
            "O2": "HEOS",
            "N2": "BICUBIC",
        },
        "T_unit": "C",
        "h_unit": "kJ / kg",
        "m_unit": "kg / s",
        "h_range": [150, 3000]
    }

If you are having trouble applying these changes, you are welcome to open an
issue on our `github repository <https://github.com/oemof/tespy/issues>`_.

Example
#######
We have added a code example below to underline the changes regarding the bus
usage. Simply, a pump is connected to a source and a sink. The pump's
efficiency and pressure rise are defined. We define three different busses
and add the pump to these busses with a given efficiency value of :code:`0.95`.

.. code-block:: python

    from tespy.components import pump, sink, source
    from tespy.connections import bus, connection
    from tespy.networks import network

    nw = network(fluids=['H2O'], p_unit='bar', T_unit='C')

    si = sink('sink')
    so = source('source')
    pu = pump('pump')

    so_pu = connection(so, 'out1', pu, 'in1')
    pu_si = connection(pu, 'out1', si, 'in1')

    nw.add_conns(so_pu, pu_si)

    bus1 = bus('bus 1')
    bus1.add_comps({'comp': pu, 'char': 0.95, 'base': 'bus'})

    # this yields a bus value smaller than the component value!!
    bus2 = bus('bus 2')
    bus2.add_comps({'comp': pu, 'char': 0.95, 'base': 'component'})

    bus3 = bus('bus 3')
    bus3.add_comps({'comp': pu, 'char': 1 / 0.95, 'base': 'component'})

    nw.add_busses(bus1, bus2, bus3)

    so_pu.set_attr(fluid={'H2O': 1}, m=10, p=5, T=20)
    pu_si.set_attr(p=10)

    pu.set_attr(eta_s=0.75)

    nw.solve('design')
    nw.print_results()

As you can see, the components value of the bus will always be the same. Due to
the efficiency definitions as mentioned in the new features, the bus value of
bus3 and bus1 are identical. bus3 implements the method applied so far (in case
of a motor at least) and bus1 implements the new efficiency definition based on
the bus value. For bus2 the efficiency definition is based on the component,
thus the bus value is lower than the component value (which would be great in
case of a motor, but unfortunately some thermodynamic experts may have issues
with that...).

Contributors
############
- Francesco Witte (`@fwitte <https://github.com/fwitte>`_)
- `@jfreissmann <https://github.com/jfreissmann>`_
