Local installation instructions

Installation

Create a new conda environment for hercules:

conda create --name hercules python=3.11
conda activate hercules

If you haven’t already cloned hercules:

git clone https://github.com/NREL/hercules

Then,

pip install -e hercules

Possibly, cd into hercules and switch to the develop branch.

SEAS is also required for hercules. To install SEAS, use

pip install https://github.com/NREL/SEAS/blob/main/SEAS.tar.gz?raw=true

If this fails, the following may work instead (but you need permissions):

git clone https://github.nrel.gov/SEAS/SEAS
cd SEAS
git fetch --all
git switch dv/emuwind

Older versions of git (e.g. the one on Eagle) don’t have the switch feature; instead, use

git checkout dv/emuwind

Then,

cd ..
pip install -e SEAS

A python electrolyzer model is also required for hercules. To install the electrolyzer, use

git clone git@github.com:NREL/electrolyzer.git
cd electrolyzer
git fetch --all
git switch develop

Older versions of git (e.g. the one on Eagle) don’t have the switch feature; instead, use

git checkout develop

Then,

cd ..
pip install -e electrolyzer

NREL’s PySAM software is also required for hercules. To install, use

pip install nrel-pysam==4.2.0

If you run hercules and get an error that pyyaml is missing, you may also need to install it using

conda install -c conda-forge pyyaml

NREL’s Wind Hybrid Open Controller (WHOC) software is used to implement controllers in the Hercules platform. This package is not essential to run Hercules by itself, but is needed to implement any controls in the platform. Example 06 has an example of how this is used to control a battery based on wind farm power output.

To install: Go back to herc_root

git clone git@github.com:NREL/wind-hybrid-open-controller.git
cd wind-hybrid-open-controller
git fetch --all
pip install -e .

Note: if you want the newest updates to the WHOC repository, you can checkout the develop branch instead of the main branch.

Running [Local]

To run locally using a standin for AMR-Wind, launch 3 separate terminals. In each, conda activate your hercules environment (conda  activate hercules).

In the first terminal, run

helics_broker -f 2 --consoleloglevel=trace --loglevel=debug --local_port=$HELICS_PORT &

from any directory.

In the second and third terminals, navigate to hercules/example_case_folders/example_sim_05 (you’ll need to be on the develop branch of hercules). Then, in one of these terminals, run

python hercules_runscript_dummy_amr.py amr_input.inp

and in the other, run

python hercules_runscript.py hercules_input_000.yaml

The first of these launches the dummy stand-in for AMR-wind, and the second launches the hercules emulator. These will connect to the helics_broker and run the co-simulation. You should see printout from both the dummy AMR-wind process and the hercules emulator printed to your screen.

Alternatively, the bash files in each example are set up to be run from the terminal using

./bash_script.sh

However, if the simulation hangs, be sure to check if there are multiple processes running with

ps

which will tell you all of the processes currently working. You can kill processes that you do not want by using the kill command, paired with the process ID (filled into the blank in the command below).

kill <PID>

Running [Kestrel]

Running hercules in full requires installing AMR-Wind (likely on Kestrel/HPC). The steps are detailed in section HPC Installation.