From 115208471db5501757356e0ac90cbcb0828cbfe0 Mon Sep 17 00:00:00 2001 From: ebalogun01 <42688418+ebalogun01@users.noreply.github.com> Date: Tue, 19 Dec 2023 20:53:38 -0800 Subject: [PATCH] improving readme --- README.md | 27 ++++++++++++++++++--------- doc_images/app_run_readme.png | Bin 0 -> 16637 bytes 2 files changed, 18 insertions(+), 9 deletions(-) create mode 100644 doc_images/app_run_readme.png diff --git a/README.md b/README.md index 3a4bd7c4..6ac46190 100644 --- a/README.md +++ b/README.md @@ -150,7 +150,7 @@ voltage violations per ANSI C84.1. The file also generates voltage distribution SIMULATION_FOLDER variable which is the string of the path where the powerflow simulation output voltages at each node exist. -`load_post_opt_costs.py` - This module is calculates the levelized cost of energy and populates into tables/cost matrices, which are saved in the +`load_post_opt_costs.py` - This module calculates the levelized cost of energy and populates into tables/cost matrices, which are saved in the respective files and folders. The module also generates plots for the cost analysis. `cost_analysis.py` - This module contains the `CostEstimator` class, which estimates the cost of the different grid and DER components @@ -158,16 +158,25 @@ from the simulation. ## How to run Create a new environment using `conda env create --name -f environment.yml`OR -install packages listed in the environment manually (RECOMMENDED) -Ensure gridlabd is installed by following recommended installation method. +install packages listed in the environment manually. You can also use the `requirements.txt` file to install the required packages. -For battery test case: -* Navigate to `test_cases/battery/feeder_population` and run `feeder_population.py`. This uses the +Ensure gridlabd is installed by following recommended installation method if using the online (MPC) power system co-simulation functionality. + +For offline (One-shot) optimization simulation: +* Open the `default_user_inputs.json` file in the root folder and modify the parameters as needed. The prepopulated + fields can be modified. Once the fields are modified as desired, navigate to `app.py` which is also in the root directory. Make sure the *test* is set to *False* (see below) in the `app.py` file. + + + Then run `app.py`. This will run the simulation and generate the results in the `results` folder under the `analysis` directory. To perform post-simulation cost + analysis, navigate to the `analysis` folder and run `load_post_opt_costs.py`. This will generate the cost analysis plots and tables in the `analysis` folder. + +For online MPC battery test case: +* Navigate to `test_cases/battery/feeder_population` and run `feeder_population_collocated.py` for collocated (DEFAULT) case or `feeder_population_centralized.py`. This uses the `test_cases/battery/feeder_population/config.txt` settings to prepare the power system and populate the secondary - distribution network with time-varying base loads, EV charging stations, with the required transformers. -* Once confirmed that `feeder_population.py` has run successfully and generates the required `IEEE123_secondary.glm` and - `IEEE123_populated.glm` files, you are done with the initial pre-simulation run prep. -* Now navigate one level of out `/feeder_population` and run scenarios.py using `python3 scenarios.py` + distribution network with time-varying base loads, EV charging stations, Distributed Energy Resources (DERs - Solar, Storage), and required transformers. +* Once confirmed that `feeder_population_.py` (CASE_TYPE is either collocated or centralized) has run successfully and generates the required `IEEE123_secondary.glm` and + `IEEE123_populated.glm` files, you are done with the initial pre-simulation run preparation. +* Now navigate one level of out `/feeder_population` and run scenarios.py using `python3 scenarios.py` or `gridlabd python scenarios.py` (recommended). For base case: * Navigate to `EV50_cosimulation/feeder_population` and run `feeder_population.py`. This uses the diff --git a/doc_images/app_run_readme.png b/doc_images/app_run_readme.png new file mode 100644 index 0000000000000000000000000000000000000000..7a06afb8e7b3ff39e5f50a74e147cabff12f87a8 GIT binary patch literal 16637 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 Qe