doc: updated sphinx docs and python doc strings for v1.1

momargoh · Apr 6, 2020 · 18dfd8a · 18dfd8a
1 parent 4c99209
commit 18dfd8a
Show file tree

Hide file tree

Showing 83 changed files with 14,099 additions and 17,104 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -5,8 +5,8 @@ CHANGELOG
 .. contents::
    :depth: 2
 
-[Unreleased]
--------------
+[1.1.0] - 06/04/2020
+------------------------------
 
 - The latest version of MCycle will be uploaded to PyPI once the cross-platform build requirements are sorted (looking into using skbuild).
 - It is planned to be able to choose alternative thermodynamic properties backends (such as `thermo <https://pypi.org/project/thermo/>`_)

diff --git a/docs/bases/mcabstractbase.rst → docs/bases/abc.rst b/docs/bases/mcabstractbase.rst → docs/bases/abc.rst
@@ -1,6 +1,6 @@
-MCycle Abstract Base Classes
+Abstract Base Class
 =============================
-.. automodule:: mcycle.bases.mcabstractbase
+.. automodule:: mcycle.bases.abc
    :members:
    :private-members:
    :inherited-members:

diff --git a/docs/bases/contents.rst b/docs/bases/contents.rst
@@ -3,7 +3,7 @@ Base Classes
 .. toctree::
    :maxdepth: 4
 
-   mcabstractbase
+   abc
    component
    config
    cycle

diff --git a/docs/bases/methods.rst b/docs/bases/methods.rst
diff --git a/docs/components/contents.rst b/docs/components/contents.rst
@@ -3,6 +3,7 @@ Component Classes
 .. toctree::
    :maxdepth: 4
 
+   general
    compressors
    coolers
    expanders

diff --git a/docs/components/general.rst b/docs/components/general.rst
@@ -0,0 +1,12 @@
+General Classes
+====================
+.. autosummary::
+     :toctree: 
+
+     mcycle.components.general.FixedOut
+
+
+.. automodule:: mcycle.components.general
+   :members:
+   :inherited-members:
+   :show-inheritance:
diff --git a/docs/components/hxs.rst b/docs/components/hxs.rst
@@ -6,15 +6,24 @@ Heat Exchanger Classes
 .. autosummary::
      :toctree: 
 
+     mcycle.components.hxs.flowconfig.HxFlowConfig
      mcycle.components.hxs.hx_basic.HxBasic
      mcycle.components.hxs.hxunit_basic.HxUnitBasic
      mcycle.components.hxs.hx_basicplanar.HxBasicPlanar
      mcycle.components.hxs.hxunit_basicplanar.HxUnitBasicPlanar
      mcycle.components.hxs.hx_plate.HxPlate
      mcycle.components.hxs.hxunit_plate.HxUnitPlate
+     mcycle.components.hxs.hx_plate.HxPlateCorrugated
+     mcycle.components.hxs.hx_plate.HxPlateFin
 
 
 
+HxFlowConfig Class
+------------------
+.. automodule:: mcycle.components.hxs.flowconfig
+   :members:
+   :inherited-members:
+
 HxBasic Class
 ------------------
 .. automodule:: mcycle.components.hxs.hx_basic
@@ -57,3 +66,17 @@ HxUnitPlate Class
    :inherited-members:
    :show-inheritance:
 
+
+HxPlateCorrugated Class
+------------------------
+.. automodule:: mcycle.components.hxs.hx_platecorrugated
+   :members:
+   :inherited-members:
+   :show-inheritance:
+
+HxPlateFin Class
+------------------------
+.. automodule:: mcycle.components.hxs.hx_platefin
+   :members:
+   :inherited-members:
+   :show-inheritance:
diff --git a/docs/conf.py b/docs/conf.py
@@ -52,17 +52,17 @@
 
 # General information about the project.
 project = 'MCycle'
-copyright = '2017, Momar Hughes'
+copyright = '2020, Momar Hughes'
 author = 'Momar Hughes'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '1.0'
+version = '1.1'
 # The full version, including alpha/beta/rc tags.
-release = '1.0.0'
+release = '1.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/docs/constants.rst b/docs/constants.rst
@@ -0,0 +1,105 @@
+MCycle Constants
+================================
+
+Many of the constants here are repetitions of CoolProp constants originally defined in structs. Cython currently doesn't offer a way to define a struct that can be accessed at both the Cython level and Python level (ie, there is no ``cpdef struct`` yet), hence these constants are just repeated as is.
+
+MCycle constants must be defined and declared in the file ``mcycle._constants.pyx``. The setup script will automatically generate ``mcycle.constants.py``.
+
+.. note:: For developers: the ``.py`` version should only be used in pure Python modules/scripts, otherwise always ``cimport`` the required constants from the ``.pyx`` file.
+
+
+Tolerances
+***********
+``TOLABS_X`` : double. 1e-10. Tolerance of quality for determining whether FlowState instance is in the two-phase liquid-vapour region.
+
+CoolProp input_pairs
+*********************
+unsigned char : Copy of CoolProp ``input_pairs`` struct values. See `CoolProp documentation <http://www.coolprop.org/_static/doxygen/html/namespace_cool_prop.html#a58e7d98861406dedb48e07f551a61efb>`_.
+
+CoolProp imposed phases
+************************
+unsigned char : Copy of CoolProp ``phases`` struct values. See `CoolProp documentation <http://www.coolprop.org/_static/doxygen/html/namespace_cool_prop.html#a99d892f7b3bb9808265335ac1efb858f>`_.
+
+MCycle PHASE
+************************
+unsigned char : Mostly a copy of CoolProp ``phases`` with a two additional phases for the saturated liquid and vapour points.
+
+=====  ========================================================== 
+Value  phase    
+=====  ========================================================== 
+0      PHASE_LIQUID 
+1      PHASE_SUPERCRITICAL
+2      PHASE_SUPERCRITICAL_GAS  
+3      PHASE_SUPERCRITICAL_LIQUID
+4      PHASE_CRITICAL_POINT
+5      PHASE_VAPOUR, PHASE_VAPOR, PHASE_GAS
+6      PHASE_TWOPHASE
+7      PHASE_UNKNOWN
+8      PHASE_NOT_IMPOSED
+9      PHASE_SATURATED_LIQUID
+10     PHASE_SATURATED_VAPOUR, PHASE_SATURATED_VAPOR
+=====  ==========================================================  
+
+MCycle UNITPHASE
+************************
+unsigned char : Combinations of pairs of phases (inlet phase & outlet phase), used when components are unitised. Used to look up heat transfer methods in :meth:`METHODS <mcycle.defaults.METHODS>`.
+
+=====  ========================================================== 
+Value  unit phase    
+=====  ========================================================== 
+0      UNITPHASE_NONE 
+1      UNITPHASE_ALL
+2      UNITPHASE_LIQUID  
+3      UNITPHASE_VAPOUR, UNITPHASE_VAPOR, UNITPHASE_GAS
+4      UNITPHASE_TWOPHASE_EVAPORATING, UNITPHASE_TP_EVAP
+5      UNITPHASE_TWOPHASE_CONDENSING, UNITPHASE_TP_COND
+6      UNITPHASE_SUPERCRITICAL
+7      UNITPHASE_ALL_SINGLEPHASE
+8      UNITPHASE_ALL_TWOPHASE, UNITPHASE_ALL_TP
+=====  ==========================================================
+
+MCycle TRANSFER
+************************
+unsigned char : Different energy transfer mechanisms.
+
+=====  ========================================================== 
+Value  transfer mechanisms   
+=====  ========================================================== 
+0      TRANSFER_NONE 
+1      TRANSFER_ALL
+2      TRANSFER_HEAT  
+3      TRANSFER_FRICTION
+=====  ==========================================================  
+
+MCycle FLOW
+************************
+unsigned char : Component flows.
+
+=====  ========================================================== 
+Value  flow 
+=====  ========================================================== 
+0      FLOW_NONE 
+1      FLOW_ALL
+2      FLOW_PRIMARY, FLOW1, WORKING_FLUID  
+3      FLOW_SECONDARY, FLOW2, SECONDARY_FLUID
+=====  ==========================================================    
+
+MCycle FLOWSENSE
+************************
+unsigned char : Heat exchanger flow sense.
+
+=====  ========================================================== 
+Value  flow sense
+=====  ========================================================== 
+0      FLOWSENSE_UNDEFINED 
+1      COUNTERFLOW
+2      PARALLELFLOW
+3      CROSSFLOW
+=====  ==========================================================
+
+
+MCycle Info
+************
+``SOURCE_URL`` : str. ``'https://github.com/momargoh/MCycle'``. Url of source code repo.
+
+``DOCS_URL`` : str. ``'https://mcycle.momarhughes.com'``. Url of hosted documentation.
diff --git a/docs/defaults.rst b/docs/defaults.rst
@@ -12,12 +12,9 @@ Attributes
 .. attribute:: mcycle.defaults.TOLREL
 
   double : General relative tolerance used for convergence of component and cycle functions. Defaults to 1e-7.
-.. attribute:: mcycle.defaults.TOLABS_X
-
-  double : Absolute tolerance used for the quality of fluids, particularly determining if a fluid is a saturated liquid or vapour. Defaults to 1e-10.
 .. attribute:: mcycle.defaults.DIV_T
 
-  double : Increment of temperature for unitisation processes [K]; lower value = higher accuracy. Defaults to 5.
+  double : Increment of temperature for unitisation processes [K]; lower value = higher accuracy. Defaults to 5 K.
 .. attribute:: mcycle.defaults.DIV_X
 
   double : Increment of quality for unitisation processes [-]; lower value = higher accuracy. Defaults to 0.1.
@@ -32,10 +29,10 @@ Attributes
   int : Maximum number of walls for a Component (eg; heat exchangers). Defaults to 200.
 .. attribute:: mcycle.defaults.TRY_BUILD_PHASE_ENVELOPE
 
-  bool : Get CoolProp to always try to build the phase envelope for mixtures. May slow computations if CoolProp repeatedly fails to do so. Defaults to True.
+  bool : Get CoolProp to try to build the phase envelope for FlowState mixtures during construction. If CoolProp fails to do so the ``_canBuildPhaseEnvelope`` attribute is set to ``False`` which overrides ``TRY_BUILD_PHASE_ENVELOPE`` to prevent wasting computation time on repeated failures. Defaults to True.
 .. attribute:: mcycle.defaults.GRAVITY
 
-  double : Vertical cceleration due to gravity. Defaults to 9.80665 [m/s^2].
+  double : Vertical cceleration due to gravity. Defaults to 9.80665 m/s^2.
 .. attribute:: mcycle.defaults.COOLPROP_EOS
 
   str : CoolProp Equation of State backend. Must be 'HEOS' or 'REFPROP', depending on whether RefProp backend has been configured (see `using RefProp <http://www.coolprop.org/coolprop/REFPROP.html>`_, `primary backends <http://www.coolprop.org/develop/backends.html#derived-backends>`_). Defaults to 'HEOS'.
@@ -51,93 +48,49 @@ Attributes
 .. attribute:: mcycle.defaults.PLOT_FORMAT
 
   str : File format for plots. Must be 'png' or 'jpg'. Defaults to 'png'.
+.. attribute:: mcycle.defaults.PLOT_COLOR
+
+  list of str : List of plot colours for distinguishing plotlines. Can be set to a list of the same colour if not required. See `link to tutorial <https://matplotlib.org/3.1.0/tutorials/colors/colors.html>`_ for more info. Defaults to ``['C0', 'C1', 'C2', 'C3', 'C4', 'C5', 'C6', 'C7', 'C8', 'C9']``.
+.. attribute:: mcycle.defaults.PLOT_LINESTYLE
+
+  list : List of linestyles for distinguishing plotlines. See `link to documentation <https://matplotlib.org/3.1.0/gallery/lines_bars_and_markers/linestyles.html>`_ for more info on defining linestyles.
+.. attribute:: mcycle.defaults.PLOT_MARKER
+
+  list of str : List of markers for distinguishing plotlines. Set to [''] if you do not require markers. See `link to documentation <https://matplotlib.org/3.1.0/api/markers_api.html>`_ for more info.
 .. attribute:: mcycle.defaults.UNITS_SEPARATOR_NUMERATOR
 
-  str : Separator style for the numerator of units; ie: 'kW.h' compared to 'kW-h', or 'kW h'. Defaults to '.'.
+  str : Separator style for the numerator of units; ie: 'W.h' compared to 'W-h', or 'W h'. Defaults to ``'.'``.
 .. attribute:: mcycle.defaults.UNITS_SEPARATOR_DENOMINATOR
 
   str : Separator style for the denominator of units; ie: 'J/kg.K' compared to 'J/kg-K', or 'J/kg/K'.Defaults to '.'.
+.. attribute:: mcycle.defaults.UNITS_FORMAT
+
+  str : Style of spacing between value and units. Must be '', 'parentheses', 'brackets', 'braces' or 'comma', with or without suffix '-nospace'. Eg, 'comma' would produce ``1.0, m^3/kg``, 'comma-nospace' would produce ``1.0,m^3/kg``, 'braces' would produce ``1.0 {m^3/kg}``. Defaults to 'comma'.
 .. attribute:: mcycle.defaults.PRINT_FORMAT_FLOAT
 
-  str : Format for printing floats, used with Python strings' format() method (see `documentation <https://docs.python.org/3.6/library/string.html#formatspec>`_). Defaults to '{:.4e}'.
+  str : Format for printing floats, used with Python strings' format() method (see `documentation <https://docs.python.org/3.6/library/string.html#formatspec>`_). Defaults to ``'{: .4e}'``.
 .. attribute:: mcycle.defaults.RST_HEADINGS
 
   list : Characters used for successive levels of reStructuredText headings. Defaults to ['=', '-', '^', '"'].
+.. attribute:: mcycle.defaults.CONFIG
+
+  Config : Default ``Config`` instance used in classes with a ``config`` attribute. When constructing, set ``config=None`` to use this default instance. This promotes sharing of a single ``Config`` instance throughout a script, as opposed to each individual component/class having its own. Defaults to ``None`` which is then set to ``Config()`` by :meth:`check() <mcycle.defaults.check>` during importation of MCycle.
 .. attribute:: mcycle.defaults.METHODS
 
-  dict : Dictionary of methods set to Config.method attribute. Defaults to
-  {'HxPlateCorrChevronHeatWf': {
-                     "sp": "chisholmWannairachchi_sp",
-                     "liq": "chisholmWannairachchi_sp",
-                     "vap": "chisholmWannairachchi_sp",
-                     "tpEvap": "yanLin_tpEvap",
-                     "tpCond": "hanLeeKim_tpCond"
-                 },
-                 'HxPlateCorrChevronFrictionWf': {
-                     "sp": "chisholmWannairachchi_sp",
-                     "liq": "chisholmWannairachchi_sp",
-                     "vap": "chisholmWannairachchi_sp",
-                     "tpEvap": "yanLin_tpEvap",
-                     "tpCond": "hanLeeKim_tpCond"
-                 },
-                 'HxPlateCorrChevronHeatSf': {
-                     "sp": "chisholmWannairachchi_sp",
-                     "liq": "chisholmWannairachchi_sp",
-                     "vap": "chisholmWannairachchi_sp"
-                 },
-                 'HxPlateCorrChevronFrictionSf': {
-                     "sp": "chisholmWannairachchi_sp",
-                     "liq": "chisholmWannairachchi_sp",
-                     "vap": "chisholmWannairachchi_sp"
-                 },
-                 'HxPlateFinOffsetHeatWf': {
-                     "sp": "manglikBergles_offset_sp",
-                     "liq": "manglikBergles_offset_sp",
-                     "vap": "manglikBergles_offset_sp",
-                     "tpEvap": "",
-                     "tpCond": ""
-                 },
-                 'HxPlateFinOffsetFrictionWf': {
-                     "sp": "manglikBergles_offset_sp",
-                     "liq": "manglikBergles_offset_sp",
-                     "vap": "manglikBergles_offset_sp",
-                     "tpEvap": "",
-                     "tpCond": ""
-                 },
-                 'HxPlateFinOffsetHeatSf': {
-                     "sp": "manglikBergles_offset_sp",
-                     "liq": "manglikBergles_offset_sp",
-                     "vap": "manglikBergles_offset_sp"
-                 },
-                 'HxPlateFinOffsetFrictionSf': {
-                     "sp": "manglikBergles_offset_sp",
-                     "liq": "manglikBergles_offset_sp",
-                     "vap": "manglikBergles_offset_sp"
-                 },
-                 'HxPlateSmoothHeatWf': {
-                     "sp": "gnielinski_sp",
-                     "liq": "gnielinski_sp",
-                     "vap": "gnielinski_sp",
-                     "tpEvap": "shah_tpEvap",
-                     "tpCond": "shah_tpCond"
-                 },
-                 'HxPlateSmoothFrictionWf': {
-                     "sp": "gnielinski_sp",
-                     "liq": "gnielinski_sp",
-                     "vap": "gnielinski_sp",
-                     "tpEvap": '',
-                     "tpCond": ''
-                 },
-                 'HxPlateSmoothHeatSf': {
-                     "sp": "gnielinski_sp",
-                     "liq": "gnielinski_sp",
-                     "vap": "gnielinski_sp"
-                 },
-                 'HxPlateSmoothFrictionSf': {
-                     "sp": "gnielinski_sp",
-                     "liq": "gnielinski_sp",
-                     "vap": "gnielinski_sp"
-                 }}
+  dict : Dictionary of methods set to :meth:`Config.methods <mcycle.bases.config.Config.methods>` attribute.
+.. attribute:: mcycle.defaults.DIMENSIONS
+
+  dict : Dictionary of attribute dimensions looked up by ``summary`` methods. Each dictionary value is another dictionary containing a default value under the ``''`` key, and class-specific values where necessary. Eg, for attribute ``'h'``, the value is the dictionary::
+    
+   'h': {
+        '': 'power/area-temperature',
+        'GeomHxPlateFinStraight': 'length',
+        'GeomHxPlateFinOffset': 'length',
+        'FlowState': 'energy/mass',
+        'FlowStatePoly': 'energy/mass'
+    },
+
+So if the class of the object that has called ``summary`` is ``FlowState`` the dimension returned is ``'energy/mass'`` (enthalpy), if the object is not listed in the above dictionary the dimension returned is ``'power/area-temperature'`` (heat transfer coefficient for heat exchangers).
 
 Methods
 --------

diff --git a/docs/examples/contents.rst b/docs/examples/contents.rst
@@ -5,5 +5,9 @@ Examples
    :maxdepth: 3
 
    quickstart
-   hughes2017
+
+
+quickstart
+-----------
+:doc:`examples/quickstart`