From 8f4f5a64712743dda8b86965b009fd30db920fff Mon Sep 17 00:00:00 2001
From: Max <max@chp1.net>
Date: Mon, 2 Jan 2023 21:20:33 +0100
Subject: [PATCH] add hints for numpy and pandas

---
 docs/source/index.rst        |  4 ++++
 docs/source/pyXSteamDemo.rst | 43 +++++++++++++++++++++++++++++++-----
 2 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 572875e..244e6d3 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -25,6 +25,10 @@ and also functions for calculations on heavy water. This includes:
 * IAPWS R4
 * IAPWS R14
 
+Usage Examples
+**************
+Check out the examples given in :doc:`pyXSteamDemo` for a quick overview of how to use pyXSteam in different use cases.
+
 Notes
 *****
 Density (rho)
diff --git a/docs/source/pyXSteamDemo.rst b/docs/source/pyXSteamDemo.rst
index 49b97b3..7d99a8b 100644
--- a/docs/source/pyXSteamDemo.rst
+++ b/docs/source/pyXSteamDemo.rst
@@ -2,7 +2,7 @@ Tutorial and Demos
 ##################
 
 Usage
-+++++
+*****
 
 Simple Example::
 
@@ -25,7 +25,7 @@ To enable logging, add the following lines to your code::
     logger.addHandler(sh)
 
 Calculate single values
-+++++++++++++++++++++++
+=======================
 This is a simple example::
 
     >>> from pyXSteam.XSteam import XSteam
@@ -35,8 +35,29 @@ This is a simple example::
     >>> steam_table.tcV_p(1)
     0.02475366759235046
 
+Usage with numpy
+================
+By converting one to the functions to a NumPy universal function it is easy to use pyXSteam on NumPy arrays::
+
+    >>> npv_pt = np.frompyfunc(steam_table.v_pt, 2, 1)
+
+* `NumPy documentation for frombyfunc <https://numpy.org/doc/stable/reference/generated/numpy.frompyfunc.html>`_
+* `pyXSteamDemo.py <https://github.com/drunsinn/pyXSteam/blob/master/bin/pyXSteamDemo.py>`_
+
+Usage with pandas
+=================
+Using pandas together with pyXSteam is very easy as well. Using
+the `apply <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.apply.html>`_ function and a
+`lambda <https://docs.python.org/3/reference/expressions.html#lambda>`_ you can add a new column based on the
+values of other columns::
+
+    >>> df['h'] = df.apply(lambda x: steamTable.h_pt(x.P, x.T), axis=1)
+
+* `Pandas documentation on DataFrame.apply <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.apply.html>`_
+* `Python documentation on lambdas <https://docs.python.org/3/reference/expressions.html#lambda>`_
+
 Generate Diagrams
-+++++++++++++++++
+=================
 Diagrams based on the calculated values can easily be created using numpy and matplotlib.
 
 Example: To draw a T(p) diagram showing the saturation curve::
@@ -54,10 +75,10 @@ Example: To draw a T(p) diagram showing the saturation curve::
     pyplot.setp(line1, linewidth=1, color='b')
     pyplot.show()
 
-For more demos, see pyXSteamDemo.py
+For more demos, see `pyXSteamDemo.py <https://github.com/drunsinn/pyXSteam/blob/master/bin/pyXSteamDemo.py>`_
 
 Heavy Water functions
-+++++++++++++++++++++
+=====================
 The functions to calculate values for heavy water are available through the
 class XSteamHW
 
@@ -65,6 +86,18 @@ class XSteamHW
     >>> steam_table = XSteamHW(XSteam.UNIT_SYSTEM_MKS)
     >>> steam_table.my_rhoT(1.2, 300.0)
 
+Content of the demo files
+*************************
 
+Main demo file pyXSteamDemo.py
+==============================
 .. literalinclude:: ../../bin/pyXSteamDemo.py
     :language: python
+
+Example on how to calculate the values for a rankine cycle
+==========================================================
+Matlab example from converted example from Stu Blair converted to python
+Original can be found at `his github page <https://github.com/stu314159/xsteam/blob/master/Examples/SimpleRankineCycle.m>`_
+
+.. literalinclude:: ../../bin/pyXSteamRankineDemo.py
+    :language: python