Updating README in preparation for April sprint

README.md

@@ -3,32 +3,68 @@
 # emu_python
 Python (python >=3.6) front-end to emulator
 
+<!--
 # Recommended install
 set up emupy (eum_python) conda environment and pip install me into it
 OR
 use pyenv
+-->
 
-# New recommended install to work with era 5
+# Installation
+Create a new conda environment for emu_python:
+```
 conda create --name emupy python=3.8
 conda activate emupy
+```
+<!--
 git clone https://github.com/NREL/OpenOA.git
 pip install ./OpenOA
+-->
+If you haven't already cloned emu_python:
+```
+git clone https://github.com/NREL/emu_python
+```
+Then,
+```
 pip install -e emu_python
+```
+Possibly, `cd` into emu_python and switch to the 
+develop branch.
+
 
-# Please install SEAS as follows: 
+SEAS is also required for emu_python. To install 
+SEAS, use
 
 ``` pip install git+https://github.nrel.gov/SEAS/SEAS.git@dv/emuwind ```
 
+If this fails, the following may work instead:
+
+<!--
 Note from PF:
 Had trouble doing it this way on local machine so instead:
 # (Activate conda environment first)
+-->
+<!--
 git clone git@github.nrel.gov:SEAS/SEAS.git
+-->
+
+```
+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
+```
 
+<!--
 # Other steps for era 5
 Now need to add a file called APIKEY which contains the API Key you'll find in your data.planetos account
 
@@ -39,21 +75,114 @@ But I found I also had to copy it down to here:
 /Users/pfleming/opt/anaconda3/envs/emupy/lib/python3.8/site-packages/operational_analysis/toolkits/
 
 Col
+-->
 
 # Running [Local]
 
+To run locally using a dummy placeholder for AMR-Wind, launch 3 separate 
+terminals. In each, `conda activate` your emu_python environment (`conda 
+activate emu_python`). 
+
+In the first terminal, run
+```
+helics_broker -t zmq  -f 2 --loglevel="debug"
+```
+from any directory.
+
+In the second and third terminals, navigate to 
+emu_python/example_case_folders/example_sim_05 (you'll need to be on the 
+develop branch of emu_python). Then, in one of these 
+terminals, run 
+```
+python emu_runscript_dummy_amr.py amr_input.inp
+```
+and in the other, run
+```
+python emu_runscript.py emu_input_000.yaml
+```
+
+The first of these launches the dummy stand-in for AMR-wind, and the second 
+launches the emu_python 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 emu_python emulator printed to your screen.
+
+<!--
 In 4 different terminals with location set to emu_python/, type the following commands
 (This is more and more out of date)
 
 - Terminal 1: `python control_center.py`
 - Terminal 2: `python testclient.py`
 - Terminal 3: `python vis_client.py`
 - Terminal 4: `python front_end_dash.py`
+-->
 
 # Running [Eagle]
 
-### Setting up AMR-WIND
+Running emu_python in full requires installing AMR-Wind (likely on eagle/HPC).
+The steps are detailed below, and assume that you have already installed 
+the other parts of emu_python as described above under **Installation**. 
+
+### Setting up AMR-WIND 
+
+First, `deactive` your conda environment using 
+```
+conda deactivate
+```
+
+Then, clone AMR-Wind and install its required submodules. This can be done 
+using
+
+EITHER
+```
+git clone https://github.com/Exawind/amr-wind
+cd amr-wind
+git submodule update --init
+cd ..
+``` 
+OR
+``` 
+git clone --recursive https://github.com/Exawind/amr-wind
+```
+
+Now, create a new directory `build` within the main AMR-Wind repository
+```
+mkdir amr-wind/build
+```
+and copy amr-wind_buildme.sh from emu_python into it, naming the copied file 
+buildme.sh
+```
+cp emu_python/amr-wind_buildme.sh amr-wind/build/buildme.sh
+```
+
+`cd` into the build directory, set executable permissions for buildme.sh, and
+run buildme.sh
+```
+cd amrwind/build
+chmod +x buildme.sh
+./buildme.sh
+```
+
+This will begin compiling an AMR-Wind executable. The process could take 
+several minutes, during which progress updates will print to the terminal. 
+Once complete, the build directory will contain an executable named amr_wind.
+
+### Running a job
+
+For an example of running emu_python with AMR-Wind, `cd` to 
+emu_python/example_case_folders/example_sim_06/. 
+
+Change the line beginning `mpirun` to point to your compiled amr-wind 
+executable. This will appear something like:
+```
+mpirun -n 72 /path/to/amr-wind/build/amr_wind amr_input.inp >> logamr 2>&1
+```
+Make any other necessary changes to batch_script.sh, and submit it to the 
+jobs queue using
+```
+sbatch batch_script.sh
+```
 
+<!--
 ```bash
     # After connecting to eagle, reconnect or start a new screen (helpful for disconnects)
     # To detach later while keeping session: ctrl+a d
@@ -122,6 +251,7 @@ In 4 different terminals with location set to emu_python/, type the following co
     # The terminal running front_end_dash.py will show a web address
     # Enter that address into a web browser on your local machine
 ```
+-->
 
 # Order of operations
 

example_case_folders/amr-wind_buildme.sh

@@ -0,0 +1,26 @@
+module purge
+module use /nopt/nrel/apps/modules/default/modulefiles
+module load helics/helics-3.1.0_openmpi
+module load cmake
+module load netcdf-c/4.7.3/gcc-mpi
+
+cmake -DAMR_WIND_ENABLE_CUDA:BOOL=OFF \
+      -DCMAKE_INSTALL_PREFIX:PATH=./install \
+      -DAMR_WIND_ENABLE_MPI:BOOL=ON \
+      -DAMR_WIND_ENABLE_OPENMP:BOOL=OFF \
+      -DAMR_WIND_TEST_WITH_FCOMPARE:BOOL=OFF \
+      -DCMAKE_BUILD_TYPE=Release \
+      -DAMR_WIND_ENABLE_NETCDF:BOOL=ON \
+      -DAMR_WIND_ENABLE_OPENFAST:BOOL=OFF \
+      -DAMR_WIND_ENABLE_HYPRE:BOOL=OFF \
+      -DAMR_WIND_ENABLE_MASA:BOOL=OFF \
+      -DAMR_WIND_ENABLE_TESTS:BOOL=OFF \
+      -DAMR_WIND_ENABLE_FORTRAN:BOOL=OFF \
+      -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=ON \
+      -DAMR_WIND_ENABLE_ALL_WARNINGS:BOOL=ON \
+      -DBUILD_SHARED_LIBS:BOOL=ON \
+      -DAMR_WIND_ENABLE_HELICS:BOOL=ON \
+      -DHELICS_INSTALL_DIR:PATH="/nopt/nrel/apps/helics/v3.1.0_openmpi/"\
+      -DHELICS_DIR:PATH="/nopt/nrel/apps/helics/v3.1.0_openmpi/" .. 
+
+nice make -j16