Merge pull request #81 from NREL/yep/release-preparation

Updating README for public release

Author: yamilbknsu

README.md

@@ -1,6 +1,6 @@
 # Demographic Microsimulator (DEMOS)
 
-[![Docs](https://github.com/NREL/DEMOS_NREL/actions/workflows/docs.yml/badge.svg)](https://nrel.github.io/DEMOS_NREL/)
+[![Docs](https://github.com/NREL/DEMOS_NREL/actions/workflows/docs.yml/badge.svg)](https://nrel.github.io/DEMOS/)
 
 ## Overview
 The Demographic Microsimulator (DEMOS) is an agent-based simulation framework used to model the evolution of population demographic characteristics and lifecycle events, such as education attainment, marital status, and other key transitions. DEMOS modules are designed to capture the interdependencies between short-term and long-term lifecycle events, which are often influential in downstream transportation and land-use modeling.
@@ -14,32 +14,53 @@ A technical memorandum describing DEMOS is available [here](./DEMOS_Technical_Me
 *Sun, Bingrong, Shivam Sharda, Venu M. Garikapati, Mohamed Amine Bouzaghrane, Juan Caicedo, Srinath Ravulaparthy, Isabel Viegas de Lima, Ling Jin, C. Anna Spurlock, and Paul Waddell. "Demographic Microsimulator for Integrated Urban Systems: Adapting Panel Survey of Income Dynamics to Capture the Continuum of Life." Transportation Research Record (2025): 03611981251333339.*
 
 ## Usage
-> A public Docker image of DEMOS has been released. Please follow the `From Source` instructions.
 
-### Docker Container
-The docker image for demos is stored in `registry/demos:latest`. The input data and configuration file are fed to the container through volumes. Alternatively, we provide a `docker-compose` workflow that can be used.
+### Docker Compose (recommended)
+The latest docker image for demos is stored in `ghcr.io/nrel/demos:latest`. The input data and configuration file are fed to the container through volumes. Alternatively, we provide a `docker-compose` workflow that can be used.
+
+#### Prepare the configuration file and data folder
 
-For running the `docker-compose` workflow:
 ```bash
-DEMOS_CONFIG_PATH=<path-to-config> DEMOS_DATA_DIR=<path-to-data-dir> docker-compose up
+# Create a directory where to run DEMOS from
+mkdir demos
+cd demos
+
+# Create the configuration folder and retrieve an example configuration
+mkdir configuration
+cd configuration
+curl -L -o demos_config_sfbay.toml https://raw.githubusercontent.com/nrel/DEMOS/main/configuration/demos_config_sfbay.toml
+
+# Create the data folder for the output to be stored
+cd ..
+mkdir data
+# Populate the data folder
+
+# Finally, retrieve the docker-compose.yml file
+curl -L -o docker-compose.yml https://raw.githubusercontent.com/nrel/DEMOS/main/docker-compose.yml
 ```
 
-By default `DEMOS_CONFIG_PATH` is set to `./demos_config.toml` and `DEMOS_DATA_DIR` is set to `./data`, so if `data` and `demos_config.toml` are part of the current directory, no additional input is needed.
-
-Alternatively,
+Now you can run docker as follows:
 ```bash
-docker run --volume <path-to-config>:/demos/config.toml:ro --volume <path-to-data-dir>:/demos/data --platform=linux/amd64 demos
+docker compose up
 ```
-
 #### IMPORTANT for MacOS and Windows users
 > Docker imposes a global limit on how much RAM containers can allocate. DEMOS easily surpases those limits, so in order to run DEMOS in Docker, users need to access the Docker Desktop GUI and `Preferences → Resources → Memory → Increase it (at least 16-20gb)`
 
-#### Building the docker image (development only)
+Documentation for custom data requirements, configuration and overall functionality of demos can be found [in the Docs](https://nrel.github.io/DEMOS/).
+
+## Other ways to run DEMOS
+
+If you need to change either the data or configuration path:
 ```bash
-docker build -t demos:0.0.1 --platform=linux/amd64 -f Dockerfile .
+DEMOS_CONFIG_PATH=<path-to-config> DEMOS_DATA_DIR=<path-to-data-dir> docker compose up
 ```
 
-### From Source
+Alternatively, if you prefer not to use docker compose, you can specify the ccreation of volumes to your data and configuration as follows:
+```bash
+docker run --volume <path-to-config>:/demos/config.toml:ro --volume <path-to-data-dir>:/demos/data --platform=linux/amd64 ghcr.io/nrel/demos:latest
+```
+
+### Running from Source
 
 1. Clone this repository
 	```
@@ -59,30 +80,3 @@ docker build -t demos:0.0.1 --platform=linux/amd64 -f Dockerfile .
 	conda activate demos-env
 	pip install .
 	```
-
-## Running DEMOS
-
-DEMOS requires a series of input tables. Example tables are provided [here](https://app.box.com/s/tox2nflumia2g4n6rk2i0navca9pskep) for internal NREL use. It is recommended to store all the input values in the folder `data` in root of the project, but absolute values can be used by specifying them in the configuration file. You may also refer to the data description [here](https://cloud.urbansim.com/docs/general/documentation/urbansim%20block%20model%20data.html)
-
-To run demos:
-```
-python simulate.py -cfg {configuration_file}
-```
-
-
-
-A default configuration file is provided in `configuration/demos_config.toml`. The `[[tables]]` entries outline tables to be loaded. For example, we can load the `persons` and `households` table from an H5 source:
-
-```toml
-[[tables]]
-file_type = "h5"
-table_name = "persons"
-filepath = "../data/custom_mpo_06197001_model_data.h5"
-h5_key = "persons"
-
-[[tables]]
-file_type = "h5"
-table_name = "households"
-filepath = "../data/custom_mpo_06197001_model_data.h5"
-h5_key = "households"
-```