Add initial new GreenHEART (ODIES) documentation

.github/ISSUE_TEMPLATE/bug_report.md

@@ -66,7 +66,7 @@ the problem. All code and full tracebacks should be properly markdown formatted.
 ### Relevant library versions
 <!--
 Use `pip freeze` to gather the relevant versions, and use the markdown table formatting as
-demonstrated below to replacing all relavant packages and their versions.
+demonstrated below to replacing all relevant packages and their versions.
 -->
   | Package | Version |
   | ------- | ------- |

CHANGELOG.md

@@ -13,6 +13,7 @@
 - Removes support for python 3.9
 - Add steel feedstock transport costs (lime, carbon, and iron ore pellets)
 - Allow individual debt rate, equity rate, and debt/equity ratio/split for each subsystem
+- Add initial docs focused on new GreenHEART (GreenHEART) development
 - New documentation CI pipeline to publish documentation at nrel.github.io/GreenHEART/ and test
   that the documentation site will build on each pull request.
 - Placeholder documentation content has been removed from the site build

docs/CONTRIBUTING.md

@@ -81,7 +81,7 @@ met the following steps should be taken to create a new release
 
     ```bash
     git tag -a v0.1 -m "v0.1 release"
-    git push --orign v0.1
+    git push --origin v0.1
     ```
 
 6. Check that the

docs/_autosummary/greenheart.tools.eco.finance.rst

@@ -15,6 +15,7 @@ greenheart.tools.eco.finance
 
       adjust_orbit_costs
       breakout_export_costs_from_orbit_results
+      calc_financial_parameter_weighted_average_by_capex
       run_capex
       run_opex
       run_orbit

docs/_autosummary/greenheart.tools.eco.utilities.rst

@@ -13,6 +13,7 @@ greenheart.tools.eco.utilities
 
    .. autosummary::
 
+      calculate_lca
       ceildiv
       convert_layout_from_floris_for_orbit
       convert_relative_to_absolute_path

docs/_autosummary/greenheart.tools.optimization.openmdao.rst

@@ -1,4 +1,4 @@
-greenheart.tools.optimization.openmdao
+greenheart.tools.optimization.openmdao
 ======================================
 
 .. automodule:: greenheart.tools.optimization.openmdao

docs/_config.yml

@@ -4,7 +4,7 @@
 title: GreenHEART
 author: National Renewable Energy Laboratory
 # logo: logo.png
-copyright: "2024"
+copyright: "2025"
 only_build_toc_files: false
 # exclude_patterns: [_build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints", .github]
 
@@ -14,7 +14,7 @@ execute:
   execute:
   execute_notebooks: auto
   timeout: -1  # better for longer running notebooks
-  merge_streams: true  # keeps unsychronized cell outputs in a single output cell
+  merge_streams: true  # keeps unsynchronized cell outputs in a single output cell
   exclude_patterns:
     - _build
     - Thumbs.db
@@ -26,10 +26,6 @@ latex:
   latex_documents:
     targetname: book.tex
 
-# Add a bibtex file so that we can create citations
-bibtex_bibfiles:
-  - references.bib
-
 # Information about where the book exists on the web
 repository:
   url: https://github.com/NREL/GreenHEART

docs/_toc.yml

@@ -6,8 +6,32 @@ root: intro
 parts:
 - caption: Getting Started
   chapters:
-  - file: install
+    - file: getting_started/install
+    - file: getting_started/what_greenheart_does
+    - file: getting_started/expected_user_knowledge
+
+- caption: User Guide
+  chapters:
+  - file: user_guide/user_guide
+
+- caption: Examples
+  chapters:
+  - file: examples/01-green-hydrogen
+
+- caption: Developer Guide
+  chapters:
   - file: CONTRIBUTING
+  - file: developer_guide/coding_guidelines
+  - file: developer_guide/why_make_new_greenheart
+  - file: developer_guide/features_not_currently_implemented
+  - file: developer_guide/class_structure
+  - file: developer_guide/describing_whats_in_classes
+
+- caption: Miscellaneous Resources
+  chapters:
+    - file: misc_resources/FAQ
+    - file: misc_resources/glossary
+
 - caption: API Reference
   maxdepth: 3
   chapters:

docs/developer_guide/class_structure.md

@@ -0,0 +1,23 @@
+# Class structure in GreenHEART
+
+A major focus of GreenHEART is modularizing the components and system architecture so it's easier to construct and analyze complex hybrid power plants producing commodities for a variety of uses.
+As such, we've taken great care to develop a series of base classes and inherited classes to help users develop their own models.
+
+## Base classes
+
+We previously discussed converters, transporters, and storage components.
+These components each have an associated base class that contain the methods expected and used for each of those components.
+These base classes live within the `core` directory of GreenHEART.
+
+## Inherited classes
+
+Individual technology classes could inherit directly from these base classes, but we do not encourage this within GreenHEART.
+Instead, we have an additional layer of class inheritance that helps reduce duplicated code and potential errors.
+
+Let us take a PEM electrolyzer model as an example.
+Each electrolyzer model has shared methods and attributes that would be present in any valid model.
+These methods are defined at the `ElectrolyzerBaseClass` level, which inherits from `ConverterBaseClass`.
+Any implemented electrolyzer model should inherit from `ElectrolyzerBaseClass` to make use of its already built out structure and methods.
+This is shown below.
+
+![Class structure](fig_of_class_structure.png)

docs/developer_guide/coding_guidelines.md

@@ -0,0 +1,15 @@
+# Coding guidelines
+
+This document outlines the coding guidelines for GreenHEART development.
+
+## Documentation development
+
+The key to making GreenHEART more user-friendly is to have clear and concise documentation.
+This includes docstrings for functions and classes, as well as high-level documentation for the tool itself.
+We should also have a clear way to document the expected methods and attributes of classes so that users can develop their own models.
+
+## Misc. development guidelines
+
+- use Google style for docstrings
+- use numpy instead of lists for arrays
+- use type hints for function arguments and return values

docs/developer_guide/describing_whats_in_classes.md

@@ -0,0 +1,36 @@
+# Expected methods and attributes of classes
+
+Within each technology class, GreenHEART expects certain methods to be defined by the developer.
+This doc page briefly discusses those methods and their impact within GreenHEART.
+
+## Performance model
+
+Each technology class must define `get_performance_model()`, which returns an OpenMDAO system.
+This system contains the physics model for the technology.
+For a converter, this computes the outputted resources based on the inputted resources.
+The input and output resources for the performance model are all arrays with length 8760 for hourly timestepped yearly data.
+
+For example, for an electrolyzer, the performance model is an OpenMDAO system whose inputs include electricity and whose outputs include hydrogen produced.
+
+## Cost model
+
+Each technology class must also define `get_cost_model()`, which returns an OpenMDAO system containing the cost model.
+Specifically, this system must output `CapEx` and `OpEx` values for the technology.
+These values are later used in financial modeled and cost breakdowns.
+
+## Financial model (optional)
+
+Each technology class can define `get_financial_model()`, which returns an OpenMDAO system containing the financial model.
+This would override any plant level financial model, and is useful for technologies that have unique financial considerations.
+This will also be more relevant as we develop non-single-owner capabilities.
+
+## Control model (optional, unused)
+
+Each technology class can define `get_control_strategy()`.
+We do not currently use this method and instead use a top-level control strategy.
+In the future, individual technologies may have unique control strategies.
+
+```{note}
+It is possible to have a combined performance, cost, and financial model within a single OpenMDAO system, provided that it returns all the necessary values.
+For example, in the HOPP wrapper, we use a combined performance and cost model to reduce computational cost.
+```

docs/developer_guide/features_not_currently_implemented.md

@@ -0,0 +1,12 @@
+# Features not currently implemented
+
+There are many features that are not currently implemented in GreenHEART that are necessary for current or future projects.
+These will become issues on the GreenHEART GitHub repo.
+We are listing them here:
+
+- splitting out HOPP into individual systems, including dispatch
+- allowing different technologies within the same plant to be at different sites
+- saving results elegantly for plant components so they do not always need to be rerun
+- detailing the required inputs and outputs for different model types (e.g. electrolyzer) so that users can more easily add their own subsystems
+- splitters and combiners for when resources are used or produced by multiple components
+- simulating different timespans than one year at hourly timesteps (8760s)

docs/developer_guide/why_make_new_greenheart.md

@@ -0,0 +1,81 @@
+# Welcome to GreenHEART
+
+This collection of docs is focused on presenting the next iteration of GreenHEART, now called GreenHEART, acknowledging where we are now and where we want to be in the future.
+Most of these docs are written in a way that we'll be able to reuse them immediately as proper docs in the actual GreenHEART repo.
+For now, to reduce development overhead and encourage rapid iteration, we'll continue to work in this sandbox repo.
+
+Our goal with these doc pages is to communicate ideas that exist in our heads, put them to paper, and provide diagrams where helpful.
+These docs are a work in progress; please ask questions about any and all parts presented here.
+
+## Why make GreenHEART?
+
+GreenHEART has already proven itself useful as a tool that can analyze and design complex hybrid systems producing electricity, hydrogen, steel, and more.
+However, these developments came in waves across multiple disparate projects, leading to a sometimes disjointed codebase.
+In an effort to streamline and modularize GreenHEART to make it more effective and capable for necessary future studies, we are devoting time to redesigning it from the ground up.
+This page discusses some of the high-level decisions and mindsets that we've used throughout this process.
+
+## What does it mean to "modularize" GreenHEART?
+
+Most of the current implementation of GreenHEART assumes that you are modeling a certain hybrid system architecture using a limited number of specific models.
+As more projects call for using GreenHEART, we must make it easier to develop and add capability to the tool in a sustainable and clear way.
+By making the internal framework of GreenHEART more agnostic to the technologies considered in the hybrid system design, we can allow for more user-defined modularized subsystems to be considered effectively.
+
+Getting into the details, this means creating generalized components that GreenHEART can expect to behave in a certain way.
+
+We introduce the ideas of "converters", which convert one resource into another.
+Simple examples of converters include electrolyzers, wind turbines, solar PV panels, and more.
+These converters can pass resources to other converters or "storage" components via "transporter" components.
+
+Transporters include hydrogen pipelines, electricity cables, or anything that transports a resource.
+In a broad sense, these might include delivery trucks or shipping vessels, though those are more for future consideration.
+
+Storage components include batteries, hydrogen tanks; anything where you store a resource.
+
+By combining instances of these different generalized components, we can study distinct hybrid systems in GreenHEART.
+Internally, the GreenHEART framework just needs to know if a something is a converter, transporter, storage, or some other type of component.
+Additionally, this allows users to develop their own components using the expected interface, and add in custom subsystems to their hybrid plant.
+
+## Why use OpenMDAO as the internal framework for GreenHEART?
+
+Through a series of internal discussions, the GreenHEART dev team landed on using [NASA's OpenMDAO framework](https://github.com/OpenMDAO/OpenMDAO/) for this new version of the tool.
+
+Using OpenMDAO for this gives quite a few benefits:
+- a proven framework for complex data-passing within multidisciplinary systems
+- automatically-generated visualization tools to help understand models and debug them
+- internal units handling and conversion
+- built-in nonlinear solvers to resolve model coupling
+- built-in optimization and parameter sweep drivers
+- multiple existing NREL tools use OpenMDAO, including [WISDEM](https://github.com/WISDEM/WISDEM/) and [WEIS](https://github.com/WISDEM/WEIS), so we can draw from institutional knowledge
+- set up with gradient-based optimization in mind, which is not currently a focus for GreenHEART but this positions the tool well for potential future additions
+- parallelization done using MPI, which is also not currently a focus but useful for the future
+
+However, there are a few downsides to using OpenMDAO:
+- an additional layer of code that developers must consider
+- longer error stack traces that might seem daunting in the terminal
+- potentially increased computational costs depending on problem type and size
+- it isn't great at optimizing mixed-integer problems
+
+The benefits outweighed the downsides, hence the team's choice to use OpenMDAO going forward.
+Additionally, we can code GreenHEART in a way to minimize some of the potential issues, given that we're aware of them before refactoring GreenHEART.
+
+## Where does HOPP come into play?
+
+[HOPP](https://github.com/NREL/HOPP) is a well-structured and useful tool that analyzes hybrid plants producing electricity.
+GreenHEART historically calls HOPP to obtain the plant's outputted electricity, which is then used downstream to feed into electrolyzers, steel, and other components.
+The current setup of GreenHEART largely works in the same way.
+
+The end-goal of GreenHEART is to remove this call to HOPP as a monolith and instead break out the individual technologies so they are all exposed equally to GreenHEART.
+This would entail reworking the dispatch implementation so it is controlled by GreenHEART and not by HOPP, which is a non-trivial task.
+HOPP would still exist as a standalone tool, but major framework development would be done in GreenHEART.
+
+## Where should code I develop and implement live?
+
+Historically, GreenHEART has been a sort of hybrid itself, where it contains both the tool itself as well as project-specific code.
+Additionally, HOPP has been a separate tool that GreenHEART calls to obtain electricity production data and has been developed alongside GreenHEART.
+This has led to a somewhat disjointed codebase that is difficult to maintain and understand.
+
+To address this, here are guidelines for where code you develop should live:
+- If the code is specific to a project, it should live in the project's repository.
+- If the code is generalizable, could be used in multiple projects, or is a useful addition to the GreenHEART tool, it should live in the GreenHEART repository.
+- Wrappers to models that are used in GreenHEART should live in the GreenHEART repository.
+- The actual models (physics, costs, financials) should live **outside** the GreenHEART repository. Complex models might live in their own repo (e.g. BERT), whereas other models might live in the project's repository.