Merge pull request #32 from NREL/develop

Merging develop into main for v0.1.1

Author: johnjasa

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## v0.1.1 [28 October 2024]
+
+- Minor updates to examples for NAWEA workshop
+
 ## v0.1 [16 October 2024]
 
 - Project has been separated from HOPP and moved into GreenHEART, removing all HOPP infrastructure.

CONTRIBUTING.md

@@ -48,13 +48,57 @@ King, J. and Hammond, S. "[Integrated Modeling, TEA, and Reference Design for Re
 
 ## Installing from Package Repositories
 
-1. GreenHEART is available as a PyPi package:
+```bash
+pip install greenheart
+```
+
+## Installing from Source
+
+### Easiest approach (recommended)
+
+1. Using Git, navigate to a local target directory and clone repository:
+
+    ```bash
+    git clone https://github.com/NREL/GreenHEART.git
+    ```
+
+2. Navigate to `GreenHEART`
 
     ```bash
-    pip install greenheart
+    cd GreenHEART
     ```
 
-## Installing from Source
+3. Create a conda environment and install GreenHEART and all its dependencies
+
+    ```bash
+    conda env create -f environment.yml
+    ```
+
+4. Install Cbc.
+   1. If using a Unix machine (not Windows), install a final dependency
+
+        ```bash
+        conda install -y -c conda-forge coin-or-cbc=2.10.8
+        ```
+    
+    2. Windows users will have to manually install Cbc: https://github.com/coin-or/Cbc
+
+An additional step can be added if additional dependencies are required, or you plan to use this
+environment for development work.
+
+- Pass `-e` for an editable developer install
+- Use one of the extra flags as needed:
+  - `examples`: allows you to use the Jupyter Notebooks
+  - `develop`: adds developer and documentation tools
+  - `all` simplifies adding all the dependencies
+
+This looks like the following for a developer installation:
+
+```bash
+pip install -e ".[all]"
+```
+
+### Customizable
 
 1. Using Git, navigate to a local target directory and clone repository:
 
@@ -68,7 +112,8 @@ King, J. and Hammond, S. "[Integrated Modeling, TEA, and Reference Design for Re
     cd GreenHEART
     ```
 
-3. Create a new virtual environment and change to it. Using Conda and naming it 'greenheart':
+3. Create a new virtual environment and change to it. Using Conda Python 3.11 (choose your favorite
+   supported version) and naming it 'greenheart' (choose your desired name):
 
     ```bash
     conda create --name greenheart python=3.11 -y
@@ -78,12 +123,18 @@ King, J. and Hammond, S. "[Integrated Modeling, TEA, and Reference Design for Re
 4. Install GreenHEART and its dependencies:
 
     ```bash
-    conda install -y -c conda-forge coin-or-cbc=2.10.8 glpk
+    conda install -y -c conda-forge glpk
     pip install electrolyzer@git+https://github.com/jaredthomas68/electrolyzer.git@smoothing
     pip install ProFAST@git+https://github.com/NREL/ProFAST.git
     ```
 
-    Note if you are on Windows, you will have to manually install Cbc: https://github.com/coin-or/Cbc.
+    Note: Unix users should install Cbc via:
+
+    ```bash
+    conda install -y -c conda-forge coin-or-cbc=2.10.8
+    ```
+
+    Windows users will have to manually install Cbc: https://github.com/coin-or/Cbc.
 
     - If you want to just use GreenHEART:
 
@@ -109,11 +160,11 @@ King, J. and Hammond, S. "[Integrated Modeling, TEA, and Reference Design for Re
       pip install -e ".[all]"
       ```
 
-5. The functions which download resource data require an NREL API key. Obtain a key from:
+1. The functions which download resource data require an NREL API key. Obtain a key from:
 
     [https://developer.nrel.gov/signup/](https://developer.nrel.gov/signup/)
 
-6. To set up the `NREL_API_KEY` and `NREL_API_EMAIL` required for resource downloads, you can create
+2. To set up the `NREL_API_KEY` and `NREL_API_EMAIL` required for resource downloads, you can create
    Environment Variables called `NREL_API_KEY` and `NREL_API_EMAIL`. Otherwise, you can keep the key
    in a new file called ".env" in the root directory of this project.
 
@@ -124,7 +175,7 @@ King, J. and Hammond, S. "[Integrated Modeling, TEA, and Reference Design for Re
     NREL_API_EMAIL=your.name@email.com
     ```
 
-7. Verify setup by running tests:
+3. Verify setup by running tests:
 
     ```bash
     pytest
@@ -163,4 +214,5 @@ forthcoming.
 
 ## Contributing
 
-Interested in improving GreenHEART? Please see the [Contributing](./CONTRIBUTING.md) section for more information.
+Interested in improving GreenHEART? Please see the [Contributor's Guide](./docs/CONTRIBUTING.md)
+section for more information.

README.md

@@ -0,0 +1,113 @@
+# Contributing
+
+We welcome contributions in the form of bug reports, bug fixes, improvements to the documentation,
+ideas for enhancements (or the enhancements themselves!).
+
+You can find a [list of current issues](https://github.com/NREL/GreenHEART/issues) in the project's
+GitHub repo. Feel free to tackle any existing bugs or enhancement ideas by submitting a
+[pull request](https://github.com/NREL/GreenHEART/pulls).
+
+## Bug Reports
+
+* Please include a short (but detailed) Python snippet or explanation for reproducing the problem.
+  Attach or include a link to any input files that will be needed to reproduce the error.
+* Explain the behavior you expected, and how what you got differed.
+
+## Pull Requests
+
+* Please reference relevant GitHub issues in your commit message using `GH123` or `#123`.
+* Changes should be [PEP8](http://www.python.org/dev/peps/pep-0008/) compatible.
+* Keep style fixes to a separate commit to make your pull request more readable.
+* Docstrings are required and should follow the
+  [Google style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html).
+* When you start working on a pull request, start by creating a new branch pointing at the latest
+  commit on [main](https://github.com/NREL/GreenHEART).
+* The GreenHEART copyright policy is detailed in the [`LICENSE`](https://github.com/NREL/GreenHEART/blob/main/LICENSE).
+
+## Documentation
+
+When contributing new features, or fixing existing capabilities, be sure to add and/or update the
+docstrings as needed to ensure the documentation site stays up to date with the latest changes.
+
+To build the documentation locally, the following command can be run in your terminal in the main
+directory of the repository.
+
+```bash
+jupyter-book build docs/
+```
+
+In addition to generating the documentation, be sure to check the results by opening the following
+path in your browser: `file:///<path-to-greenheart>/GreenHEART/docs/_build/html/index.html`.
+
+```{note}
+If the browser appears to be out of date from what you expected to built, please try the following:
+1. Reload the page
+2. Clear your browser's cache and open the page again.
+```
+
+## Tests
+
+The test suite can be run using `pytest tests/greenheart`. Individual test files can be run by specifying them:
+
+```bash
+pytest tests/greenheart/test_hybrid.py
+```
+
+and individual tests can be run within those files
+
+```bash
+pytest tests/greenheart/test_hybrid.py::test_greenheart_system
+```
+
+When you push to your fork, or open a PR, your tests will be run against the
+[Continuous Integration (CI)](https://github.com/NREL/HOPP/actions) suite. This will start a build
+that runs all tests on your branch against multiple Python versions, and will also test
+documentation builds.
+
+## Release Process
+
+### Standard
+
+Most contributions will be into the `develop` branch, and once the threshold for a release has been
+met the following steps should be taken to create a new release
+
+1. On `develop`, bump the version appropriately, see the
+   [semantic versioning guidelines](https://semver.org/) for details.
+2. Open a pull request from `develop` into `main`.
+3. When all CI tests pass, and the PR has been approved, merge the PR into main.
+4. Pull the latest changes from GitHub into the local copy of the main branch.
+5. Tag the latest commit to match the version bump in step 1 (replace "v0.1" in all instances below),
+   and push it to the repository.
+
+    ```bash
+    git tag -a v0.1 -m "v0.1 release"
+    git push --orign v0.1
+    ```
+
+6. Check that the
+   [Test PyPI GitHub Action](https://github.com/NREL/GreenHEART/actions/workflows/publish_to_test_pypi.yml)
+   has run successfully.
+   1. If the action failed, identify and fix the issue, then
+   2. delete the local and remote tag using the following (replace "v0.1" in all instances just like
+      in step 5):
+
+      ```bash
+      git tag -d v0.1
+      git push --delete origin v0.1
+      ```
+
+   3. Start back at step 1.
+7. When the Test PyPI Action has successfully run,
+   [create a new release](https://github.com/NREL/GreenHEART/releases/new) using the tag created in
+   step 5.
+
+### Patches
+
+Any pull requests directly into the main branch that alter the GreenHEART model (excludes anything
+in `docs/`, or outside of `greenheart/` and `tests/`), should be sure to follow the instructions
+below:
+
+1. All CI tests pass and the patch version has been bumped according to the
+   [semantic versioning guidelines](https://semver.org/).
+2. Follow steps 4 through 7 above.
+3. Merge the NREL main branch back into the develop branch and push the changes.

docs/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+greenheart.simulation.greenheart\_simulation
+============================================
+
+.. automodule:: greenheart.simulation.greenheart_simulation
+
+   
+   
+   
+
+   
+   
+   .. rubric:: Functions
+
+   .. autosummary::
+   
+      run_design_options
+      run_policy_options_storage_types
+      run_policy_storage_design_options
+      run_simulation
+      run_storage_options
+      run_sweeps
+      setup_greenheart_simulation
+   
+   
+
+   
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      GreenHeartSimulationConfig
+      GreenHeartSimulationOutput
+   
+   
+
+   
+   
+   
+
+
+

docs/_autosummary/greenheart.simulation.greenheart_simulation.rst

@@ -0,0 +1,32 @@
+greenheart.simulation
+=====================
+
+.. automodule:: greenheart.simulation
+
+   
+   
+   
+
+   
+   
+   
+
+   
+   
+   
+
+   
+   
+   
+
+
+
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+
+   greenheart.simulation.greenheart_simulation
+   greenheart.simulation.technologies
+