update documentation

Author: yamilbknsu

.github/workflows/cleanup.yml

@@ -16,10 +16,12 @@ A technical memorandum describing DEMOS is available [here](./DEMOS_Technical_Me
 ## Usage
 
 ### 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.
+The latest docker image for demos is stored in `ghcr.io/NatLabRockies/demos:latest`. The input data and configuration file are fed to the container through volumes ([more info about Docker volumes](https://docs.docker.com/engine/storage/volumes/)). We provide a `docker-compose` workflow that can be used to make the process of mounting volumes easier.
 
 #### Prepare the configuration file and data folder
 
+Run the following command in the Terminal App (MacOS) or Command Prompt/PowerShell (Windows):
+
 ```bash
 # Create a directory where to run DEMOS from
 mkdir demos
@@ -28,43 +30,36 @@ cd demos
 # Create the configuration folder and retrieve an example configuration
 mkdir configuration
 cd configuration
-curl -L -o demos_config.toml https://raw.githubusercontent.com/nrel/DEMOS/main/configuration/demos_config_sfbay.toml
+curl -L -o demos_config.toml https://raw.githubusercontent.com/NatLabRockies/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
+curl -L -o docker-compose.yml https://raw.githubusercontent.com/NatLabRockies/DEMOS/main/docker-compose.yml
 ```
 
-Now you can run docker as follows:
+Make sure you have [Docker](https://docs.docker.com/desktop/) and [Docker Compose](https://docs.docker.com/compose/install/) installed. Now you can run docker as follows:
+
 ```bash
 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)`
+> 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)`. The amount of memory required to run DEMOS will primarily depend on the size of the input data.
 
 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
-DEMOS_CONFIG_PATH=<path-to-config> DEMOS_DATA_DIR=<path-to-data-dir> docker compose up
-```
-
-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
 
+If you prefer to create your own Python environment and run the Python code directly (for debugging or enhancing DEMOS capabilities), you can do so following these instructions:
+
 1. Clone this repository
 	```
-	git clone https://github.com/NREL/DEMOS_NREL.git
+	git clone https://github.com/NatLabRockies/DEMOS.git
 	```
 
 1. Create a virtual environment.

README.md

@@ -13,3 +13,4 @@ DEMOS documentation
    pages/intro.md
    api/modules
    pages/configuration
+   pages/advanced_configuration.md

docs/source/index.rst

@@ -0,0 +1,82 @@
+# Advanced Options for DEMOS
+
+## Configuration of calibration procedures
+
+Certain modules support calibration of the simulation output to observed values. Specific calibration parameters can be set for each module that supports it. If no configuration is provided, calibration is not performed.
+
+Calibration configuration is defined at `module-level-config.calibration_procedure` (`module-level-config` is defined differently for every module. The options are displayed [here](../api/configuration_module.rst) and in each module's documentation).
+
+For example, in the mortality module configuration we find the following:
+
+```toml
+[mortality_module_config.calibration_procedure]
+procedure_type = "rmse_error"
+tolerance_type = "absolute"
+tolerance = 1000
+max_iter = 1000
+[mortality_module_config.calibration_procedure.observed_values_table]
+file_type = "csv"
+table_name = "observed_fatalities_data"
+filepath = "../data/sf_bay_example/observed_calibration_values/mortalities_over_time_obs.csv"
+index_col = "year"
+```
+
+This section of the configuration file does a couple of things:
+- Sets the procedure type to `rmse_error` (currently the only available option)
+- Sets the Tolerance type to `absolute`. This means that DEMOS will continue to optimize the output until the absolute difference between the current value predicted and the observed is smaller than this tolerance. An alternative value for this parameter is `relative`, which changes the logic to interpret the tolerance value as relative.
+- Sets the tolerance level. If `tolerance_type` is `absolute`, this is an absolute value. Otherwise, this is a percentage
+- Sets the maximum number of iterations
+- Identifies which data to use for validation by assigning a value to `mortality_module_config.calibration_procedure.observed_values_table`. This has the same format as any other table loade d in the `tables` section of the configuration.
+
+If for example you would like to skip calibration on the mortality module, just delete or comment out all these lines corresponding to `mortality_module_config.calibration_procedure`.
+
+---
+
+Additionally, some modules (namely `employment` and `household_reorganization`) implement simultaneous calibration.
+
+**If you want to use simultaneous calibration for the `employment` module**
+
+```toml
+[employment_module_config.simultaneous_calibration_config]
+tolerance = 100
+max_iter = 2
+learning_rate = 2
+momentum_weight = 0.3
+```
+
+Due to the complexity and nuances of simultaneous calibration, the required tables of observed values (`observed_entering_workforce` and `observed_exiting_workforce`) are hard-coded, and an error will be raised if they are not loaded.
+
+<!-- **If you instead want to use simple calibration**
+
+We need to define the following:
+```toml
+[employment_module_config.enter_model_calibration_procedure]
+procedure_type = "rmse_error"
+observed_values_table = "observed_entering_workforce"
+tolerance_type = "relative"
+tolerance = 0.01
+max_iter = 1000
+
+[employment_module_config.exit_model_calibration_procedure]
+procedure_type = "rmse_error"
+observed_values_table = "observed_exiting_workforce"
+tolerance_type = "relative"
+tolerance = 0.01
+max_iter = 1000
+``` 
+
+This will allow DEMOS to execute calibration on each of the two modules in the employment module.
+
+**If you want to skip calibration, just delete these entrances from the configuration file.**-->
+
+<!-- See the example config for more options, including output tables, calibration, and module selection. -->
+
+## Selection of modules to run
+
+The `modules` parameter in the configuration file accepts a list of strings identifying the modules. By default all are included, but if you'd like to only run a selection of them you can change it. For instance to run only `aging` and `education`:
+```
+modules = [
+    "aging",
+    "education",
+]
+```