From d8573476c48ee859dec944290b8d2f98001cce42 Mon Sep 17 00:00:00 2001
From: Andre Perkins <frodre@gmail.com>
Date: Thu, 25 Feb 2021 20:55:14 -0800
Subject: [PATCH] Update readme with basic instructions

---
 README.md             | 62 ++++++++++++++++++++++++++++++++-----------
 create_lmr_py3_env.sh |  2 +-
 2 files changed, 47 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index c77b4d7..beb9728 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,57 @@
 # LMR Online
 
-Welcome to the Last Millennium Reanalysis Online (LMR Online) framework code base-- a toolset
-for climate field reconstructions using ensemble data assimilation.  This is an offshoot of
-the original LMR Framework (Hakim et al. 2016).
-This repository contains the code used for reconstructions in "Coupled Atmosphere--Ocean
-Reconstruction of the Last Millennium Using Online Data Assimilation, Perkins and Hakim,
-submitted"
+Welcome to the Last Millennium Reanalysis Online (LMR Online) framework code base-- a toolset for climate field reconstructions using ensemble data assimilation.  This is an offshoot ofthe original LMR Framework (Hakim et al. 2016). This repository contains the code used for reconstructions in "Coupled Atmosphere--Ocean Reconstruction of the Last Millennium Using Online Data Assimilation, Perkins and Hakim, submitted 2020"
 
-This package is based off of the original [LMR framework](https://www.github.com/modons/LMR)
-(Hakim et al. 2016) with enhancements to include climate forecasts via a linear inverse models,
-([pyLIM](https://www.github.com/frodre/pyLIM) from Perkins & Hakim 
-[2020](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2019MS001778)).
+This package is based off of the original [LMR framework](https://www.github.com/modons/LMR) ([Hakim et al. 2016](http://doi.org/10.1002/2016JD024751)) with enhancements to include climate forecasts via a linear inverse models, ([pyLIM](https://www.github.com/frodre/pyLIM) from Perkins & Hakim  [2020](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2019MS001778)).
 
-
-
-For more information, please see the 
-[LMR documentation page.](https://atmos.washington.edu/~wperkins/LMR/docs).
-**Note** that these docs are still in progress of being updated from original LMR
-documentation.
+The original [LMR documentation page](https://atmos.washington.edu/~hakim/LMR/docs/) has some information on components, but is currently somewhat outdated for this version.
 
 
 * Free software provided under the modified BSD License
 * Tested and running on Python 3.6+
 
+## Installation
+
+The installation requires the conda package manager.  A minimal [Miniconda](https://docs.conda.io/en/latest/miniconda.html) installation is sufficient to install the environment.
+
+To install an environment that replicates the linux environment used to perform the reconstructions, run:
+
+    ./create_lmr_py3_env.sh
+
+To change the name of the conda environment, simply adjust the `ENV` variable in that script. It defaults to `lmr_env`.
+
+Additionally, you will need to install the [pyLIM](https://www.github.com/frodre/pyLIM) package. Outside of the LMROnline directory:
+
+    git clone https://www.github.com/frodre/pyLIM
+    cd pyLIM
+    conda activate <ENV>
+    python setup.py install
+
+## Running an LMROnline Reconstruction
+
+For convenience, we provide a prepared directory on Zenodo with pre-processed data ready to run experiments from the coupled atmosphere-ocean reconstruction paper.
+
+Copy any of the configs to the LMROnline directory
+
+    cp configs\config_production_ccsm4_pagesv2_wCoral_gis_seaslinobj_offline_past1000.yml LMROnline/config.yml
+    cp LMROnline/config_templs/LMR_config_template.py LMROnline/LMR_config.py
+
+Adjust the opening lines of the configuration to match desired output directories
+
+    wrapper:
+        iter_range:  !!python/tuple [0, 10]
+        multi_seed: 89
+
+        datadir_output: /tmp/user/lmr_output
+        archive_dir: /path/to/final/output
+
+        nexp: production_ccsm4_pagesv2_wCoral_gis_seaslinobj_offline_past1000
+
+    core:
+        lmr_path: /path/to/LMR/input/data
+
+**Note** `lmr_path` must point to the directory of the pre-processed data parent directory.
 
+From the LMROnline directory, start a reconstruction with
 
+    python LMR_wrapper.py config.yml
diff --git a/create_lmr_py3_env.sh b/create_lmr_py3_env.sh
index a9cc162..2012728 100644
--- a/create_lmr_py3_env.sh
+++ b/create_lmr_py3_env.sh
@@ -1,6 +1,6 @@
 !/bin/bash
 
-ENV=test_lmr
+ENV=lmr_env
 
 conda create -y -n $ENV python=3.6.7 && \
     conda install -y -n $ENV -c conda-forge esmpy=7.1.0 && \