From 821b1376d9d0fd50558ccb9b183951b7e13bd82b Mon Sep 17 00:00:00 2001
From: msrocka <michael.srocka@gmail.com>
Date: Wed, 19 Sep 2018 14:02:40 +0200
Subject: [PATCH] added flow example

---
 README.rst | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 55 insertions(+), 4 deletions(-)

diff --git a/README.rst b/README.rst
index 99dc0dd..6d24428 100644
--- a/README.rst
+++ b/README.rst
@@ -8,7 +8,7 @@ in openLCA and processing their results outside of openLCA. The ``olca-ipc``
 package provides a convenience API for using this IPC protocol from standard
 Python (Cpython v3.6+) so that it is possible to use openLCA as a data storage
 and calculation engine and combine it with the libraries from the Python
-ecosystem.
+ecosystem (numpy, pandas and friends).
 
 The openLCA IPC protocol is based on the openLCA data exchange format which is
 specified in the `olca-schema <https://github.com/GreenDelta/olca-schema>`_
@@ -35,6 +35,57 @@ port, e.g. ``8080``, to which you connect from an IPC client:
     client = olca.Client(8080)
 
 An instance of the ``olca.Client`` class is then a convenient entry point for
-calling functions of openLCA and processing their results. Please see the
-`package documentation <https://olca-ipc.readthedocs.io/en/latest/>`_ for more
-information and examples.
+calling functions of openLCA and processing their results. The following
+examples show some typical uses cases.
+
+
+**Create and link data**
+
+The ``olca`` package contains a class model with type annotations for the
+`olca-schema <https://github.com/GreenDelta/olca-schema>`_ model that is used
+for exchanging data with openLCA. With the type annotations you should get good
+editor support (type checks and IntelliSense). You can create, update
+and link data models as defined in the openLCA schema (e.g. as for
+`processes <http://greendelta.github.io/olca-schema/html/Process.html>`_,
+`flows <http://greendelta.github.io/olca-schema/html/Flow.html>`_, or
+`product systems <http://greendelta.github.io/olca-schema/html/ProductSystem.html>`_).
+
+The ``olca.Client`` class provides methods like ``get``, ``find``, ``insert``,
+``update``, and ``delete`` to work with data. The following example shows how to
+create a new flow and link it to an existing flow property with the name `Mass`:
+
+
+.. code-block:: python
+
+    import olca
+    import uuid
+
+    client = olca.Client(8080)
+
+    # find the flow property 'Mass' from the database
+    mass = client.find(olca.FlowProperty, 'Mass')
+
+    # create a flow that has 'Mass' as reference flow property
+    steel = olca.Flow()
+    steel.id = str(uuid.uuid4())
+    steel.flow_type = olca.FlowType.PRODUCT_FLOW
+    steel.name = "Steel"
+    steel.description = "Added from the olca-ipc python API..."
+    # in openLCA, conversion factors between different
+    # properties/quantities of a flow are stored in
+    # FlowPropertyFactor objects. Every flow needs at
+    # least one flow property factor for its reference
+    # flow property.
+    mass_factor = olca.FlowPropertyFactor()
+    mass_factor.conversion_factor = 1.0
+    mass_factor.flow_property = mass
+    mass_factor.reference_flow_property = True
+    steel.flow_properties = [mass_factor]
+
+    # save it in openLCA, you may have to refresh
+    # (close & reopen the database to see the new flow)
+    client.insert(steel)
+
+
+For more information and examples see the
+`package documentation <https://olca-ipc.readthedocs.io/en/latest/>`_