Merge pull request #41 from softwareengineerprogrammer/readme-updates

README documentation updates

Author: softwareengineerprogrammer

README.rst

@@ -7,7 +7,12 @@ Overview
 .. |GEOPHIRES Logo| image:: geophires-logo.png
     :alt: GEOPHIRES Logo
 
-GEOPHIRES is a free and open-source geothermal techno-economic simulator. GEOPHIRES combines reservoir, wellbore, surface plant, and economic models to estimate the capital and operation and maintenance costs, instantaneous and lifetime energy production, and overall levelized cost of energy of a geothermal plant. Various reservoir conditions (EGS, doublets, etc.) and end-use options (electricity, direct-use heat, cogeneration) can be modeled. Users are encouraged to build upon to the GEOPHIRES framework to implement their own correlations and models.
+GEOPHIRES is a free and open-source geothermal techno-economic simulator.
+GEOPHIRES combines reservoir, wellbore, surface plant, and economic models to estimate the capital and operation and maintenance costs,
+instantaneous and lifetime energy production, and overall levelized cost of energy of a geothermal plant.
+Various reservoir conditions (EGS, doublets, etc.) and end-use options (electricity, direct-use heat, cogeneration) can be modeled.
+Users are encouraged to build upon to the GEOPHIRES framework to implement their own correlations and models.
+See the `Documentation`_ section below for more information.
 
 GEOPHIRES-X is the successor version to `GEOPHIRES v2.0 <https://github.com/NREL/GEOPHIRES-v2>`__ (see `CHANGELOG <CHANGELOG.rst>`__ for more info).
 
@@ -251,17 +256,63 @@ You may also optionally pass the output file as well::
 Documentation
 =============
 
+GEOPHIRES combines reservoir, wellbore, surface plant, and economic and cost models
+and correlations to estimate the capital and operation and maintenance costs,
+instantaneous and lifetime energy production, and overall levelized cost of energy of a
+geothermal plant.
+
+The high-level software architecture is illustrated in the diagram below. Green, orange and blue rectangles
+refer to internal GEOPHIRES components, external user-interface components, and
+external reservoir simulators (TOUGH2), respectively. Rectangles with solid outline are
+always executed during a simulation run; rectangles with dashed outline refer to optional
+or user-provided components.
+
+|GEOPHIRES Architecture Diagram|
+
+.. |GEOPHIRES Architecture Diagram| image:: References/geophires-architecture-diagram_2024-11-20.png
+    :alt: GEOPHIRES Architecture Diagram
+
+GEOPHIRES has a variety of different reservoir models including (1) Multiple parallel fractures model;
+(2) 1-Dimensional linear heat sweep model;
+(3) M/A thermal drawdown parameter model;
+(4) Percentage temperature drawdown model;
+(5) User-provided reservoir temperature production data;
+(6) Coupling to TOUGH2 external reservoir simulator;
+(7) SUTRA: Reservoir Thermal Energy Storage (RTES; also known as Underground Thermal Energy Storage - UTES);
+(8) Slender Body Theory (SBT);
+(9) Cylindrical.
+
+GEOPHIRES can simulate three different end-uses of the geothermal heat: (1)
+direct-use heat (e.g. for industrial processing heating or residential space heating);
+(2) electricity (with subcritical ORC, supercritical ORC, single-flash, or double-flash plant);
+(3) co-generation of heat and electricity. The co-generation option considers bottoming
+cycle, topping cycle, and parallel cycle.
+
+GEOPHIRES has 4 economic models to calculate the levelized cost of heat or
+electricity: (1) fixed charge rate (FCR) model;
+(2) standard discounting levelized cost model;
+(3) BICYCLE model;
+(4) CLGS.
+
+The capital and O&M costs for the different geothermal system components (exploration,
+well drilling, surface plant, etc.) are either provided by the user or calculated with built-in
+correlations.
 
 Parameters
 ----------
 
 Available parameters are documented in the `Parameters Reference <https://nrel.github.io/GEOPHIRES-X/parameters.html>`__.
 
+Note that many parameters are interrelated and/or conditionally dependent on one another;
+reviewing the GEOPHIRES example(s) relevant to your use case in the following section
+is strongly recommended to gain a working understanding of how to construct valid sets of input parameters.
+
 
 Examples
 --------
 
-GEOPHIRES includes a variety of examples demonstrating its features and case studies for different types of geothermal systems.
+GEOPHIRES includes a variety of examples input files demonstrating its features for different types of geothermal systems
+and case studies of real-world geothermal projects.
 Starting with an existing GEOPHIRES example that is similar to your intended use/application can be an easier approach to using GEOPHIRES than constructing your own inputs from scratch.
 
 Example input ``.txt`` files and corresponding case report ``.out`` files are available in the `tests/examples directory <tests/examples>`__ of the repository.
@@ -276,35 +327,39 @@ Example-specific web interface deeplinks are listed in the Link column.
      - Input file
      - Case report file
      - Link
-   * - Example 1
+   * - Example 1: EGS Electricity
      - `example1.txt <tests/examples/example1.txt>`__
      - `.out <tests/examples/example1.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=example1>`__
    * - Example 1 with Addons
      - `example1_addons.txt <tests/examples/example1_addons.txt>`__
      - `.out <tests/examples/example1_addons.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=example1_addons>`__
-   * - Example 2
+   * - Example 2: EGS Direct-Use Heat
      - `example2.txt <tests/examples/example2.txt>`__
      - `.out <tests/examples/example2.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=example2>`__
-   * - Example 3
+   * - Example 3: EGS Co-generation
      - `example3.txt <tests/examples/example3.txt>`__
      - `.out <tests/examples/example3.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=example3>`__
-   * - Example 4
+   * - Example 4: Hydrothermal Electricity
      - `example4.txt <tests/examples/example4.txt>`__
      - `.out <tests/examples/example4.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=example4>`__
-   * - Example 5
+   * - Example 5: User-Provided Reservoir Data
      - `example5.txt <tests/examples/example5.txt>`__
      - `.out <tests/examples/example5.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=example5>`__
-   * - Example 8
+   * - Example 6: TOUGH2
+     - `example6.txt <https://github.com/NREL/GEOPHIRES-v2/blob/master/Examples/example6.txt>`__\*
+     -
+     -
+   * - Example 8: Cornell Direct-Use Heat
      - `example8.txt <tests/examples/example8.txt>`__
      - `.out <tests/examples/example8.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=example8>`__
-   * - Example 9
+   * - Example 9: Cornell Electricity
      - `example9.txt <tests/examples/example9.txt>`__
      - `.out <tests/examples/example9.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=example9>`__
@@ -320,7 +375,7 @@ Example-specific web interface deeplinks are listed in the Link column.
      - `example12_DH.txt <tests/examples/example12_DH.txt>`__
      - `.out <tests/examples/example12_DH.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=example12_DH>`__
-   * - Example 13
+   * - Example 13: Redrilling due to Drawdown
      - `example13.txt <tests/examples/example13.txt>`__
      - `.out <tests/examples/example13.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=example13>`__
@@ -356,11 +411,11 @@ Example-specific web interface deeplinks are listed in the Link column.
      - `example_multiple_gradients.txt <tests/examples/example_multiple_gradients.txt>`__
      - `.out <tests/examples/example_multiple_gradients.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=example_multiple_gradients>`__
-   * - Fervo Project Red (Norbeck J.H. and Latimer T.M. 2023.)
+   * - Fervo Project Red (2023)
      - `Fervo_Norbeck_Latimer_2023.txt <tests/examples/Fervo_Norbeck_Latimer_2023.txt>`__
      - `.out <tests/examples/Fervo_Norbeck_Latimer_2023.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=Fervo_Norbeck_Latimer_2023>`__
-   * - Fervo Cape Station 1
+   * - Fervo Cape Station 1: 2023 Results
      - `Fervo_Project_Cape.txt <tests/examples/Fervo_Project_Cape.txt>`__
      - `.out <tests/examples/Fervo_Project_Cape.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=Fervo_Project_Cape>`__
@@ -389,6 +444,8 @@ Example-specific web interface deeplinks are listed in the Link column.
      - `.out <tests/examples/example_SBT_Lo_T.out>`__
      - `link <https://gtp.scientificwebservices.com/geophires?geophires-example-id=example_SBT_Lo_T>`__
 
+*\*GEOPHIRES v2.0 input file*
+
 Videos
 ------
 
@@ -399,9 +456,11 @@ Videos
 HIP-RA: Heat in Place - Resource Assessment
 -------------------------------------------
 
-* `HIP-RA-X README <src/hip_ra_x/README.md>`__
-* `HIP-RA-X Parameters Reference <https://nrel.github.io/GEOPHIRES-X/hip_ra_x_parameters.html>`__
-* A HIP-RA web interface is available at `gtp.scientificwebservices.com/hip-ra <https://gtp.scientificwebservices.com/hip-ra>`__.
+`HIP-RA-X README <src/hip_ra_x/README.md>`__
+
+`HIP-RA-X Parameters Reference <https://nrel.github.io/GEOPHIRES-X/hip_ra_x_parameters.html>`__
+
+A HIP-RA web interface is available at `gtp.scientificwebservices.com/hip-ra <https://gtp.scientificwebservices.com/hip-ra>`__.
 
 
 Monte Carlo
@@ -413,18 +472,18 @@ A Monte Carlo web interface is available at `gtp.scientificwebservices.com/monte
 
 Extending GEOPHIRES-X
 ---------------------
-* `How to extend GEOPHIRES-X <docs/How-to-extend-GEOPHIRES-X.md#how-to-extend-geophires-x>`__ user guide
+`How to extend GEOPHIRES-X <docs/How-to-extend-GEOPHIRES-X.md#how-to-extend-geophires-x>`__ user guide
 
-  - `Extension example: SUTRA <https://github.com/NREL/GEOPHIRES-X/commit/984cb4da1505667adb2c45cb1297cab6550774bd#diff-5b1ea85ce061b9a1137a46c48d2d293126224d677d3ab38d9b2f4dcfc4e1674e>`__
+`Extension example: SUTRA <https://github.com/NREL/GEOPHIRES-X/commit/984cb4da1505667adb2c45cb1297cab6550774bd#diff-5b1ea85ce061b9a1137a46c48d2d293126224d677d3ab38d9b2f4dcfc4e1674e>`__
 
 
 Additional Documentation
 ------------------------
-The `GEOPHIRES v2.0 (previous version's) user manual <References/GEOPHIRES%20v2.0%20User%20Manual.pdf>`__ describes GEOPHIRES's high-level software architecture.
 
-Theoretical basis for GEOPHIRES:  `GEOPHIRES v2.0: updated geothermal techno‐economic simulation tool <References/Beckers%202019%20GEOPHIRES%20v2.pdf>`__
+Theoretical basis for GEOPHIRES:  `GEOPHIRES v2.0: updated geothermal techno‐economic simulation tool <References/Beckers%202019%20GEOPHIRES%20v2.pdf>`__;
+accompanying `GEOPHIRES v2.0 user manual <References/GEOPHIRES%20v2.0%20User%20Manual.pdf>`__.
 
-Additional materials in `/References </References>`__
+Additional materials can be found in `/References </References>`__.
 
 
 Development