Merge pull request #30 from kbrunik/public

Updating GreenHEART Examples

README.md

@@ -48,13 +48,48 @@ 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
-    pip install greenheart
+    git clone https://github.com/NREL/GreenHEART.git
     ```
 
-## Installing from Source
+2. Navigate to `GreenHEART`
+
+    ```bash
+    cd GreenHEART
+    ```
+
+3. Create a conda environment and install GreenHEART and all its dependencies
+
+    ```bash
+    conda env create -f environment.yml
+    ```
+
+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 +103,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

environment.yml

@@ -0,0 +1,13 @@
+name: greenheart
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.11
+  - coin-or-cbc=2.10.8
+  - glpk
+  - pip
+  - pip:
+    - electrolyzer@git+https://github.com/jaredthomas68/electrolyzer.git@smoothing
+    - ProFAST@git+https://github.com/NREL/ProFAST.git
+    - "."

examples/README.md

@@ -0,0 +1,56 @@
+# Examples Overview
+
+This directory provides example Jupyter notebooks demonstrating how to use the GreenHEART tool for technoeconomic analysis of green technology applications. These workflows and calculations cover hydrogen production, steel manufacturing, ammonia synthesis, and Proton Exchange Membrane (PEM) electrolyzer modeling. GreenHEART enables co-design and simulation of an integrated renewable energy and hydrogen production plant, along with optional end-use applications.
+
+The first three notebooks focus on the GreenHEART simulation interface, which supports single analysis cases as well as optimization for levelized cost of product. The final example, `04-PEM_electrolyzer.ipynb`, illustrates how to use GreenHEART's PEM electrolyzer model.
+
+> **Note**: The `reference_plants` directory, containing reference designs for green hydrogen, ammonia, and steel plants across the U.S., will be removed in future releases. Reference plant data is now hosted at [NREL/ReferenceHybridSystemDesigns](https://github.com/NREL/ReferenceHybridSystemDesigns).
+
+## Structure
+
+- **01-green-hydrogen.ipynb**: Demonstrates a workflow for green hydrogen production using renewable energy and electrolysis.
+- **02-green-steel.ipynb**: Illustrates green steel production using hydrogen as a reducing agent via hydrogen direct reduced iron and electric arc furnace (HDRI-EAF) technology.
+- **03-green-ammonia.ipynb**: Covers green ammonia production through renewable hydrogen in the Haber-Bosch process.
+- **04-PEM_electrolyzer.ipynb**: Details the use of the GreenHEART PEM Water Electrolyzer model, including key components and operation.
+
+## Quick Start
+1. Clone the repository: 
+    ```bash
+    git clone https://github.com/NREL/GreenHEART.git
+    ```
+2. Create a conda environment from the `environment.yml`:
+    ```bash
+    conda env create -f environment.yml
+    ```
+3. 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/)
+
+4. 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.
+
+    Create a file ".env" that contains the single line:
+
+    ```bash
+    NREL_API_KEY=key
+    [email protected]
+    ```
+5. Open a Jupyter Notebook environment to explore the examples:
+
+    ```bash
+   jupyter notebook
+   ```
+
+**OR**
+1. Clone the repository: 
+    ```bash
+    git clone https://github.com/NREL/GreenHEART.git
+    ```
+2. Follow the setup instructions in the main `README.md`
+3. Open a Jupyter Notebook environment to explore the examples:
+
+    ```bash
+   jupyter notebook
+   ```
+