search

NREL / dgen

The Distributed Generation Market Demand (dGen) model simulates customer adoption of distributed energy resources (DERs) for residential, commercial, and industrial entities in the United States and other countries.
BSD 3-Clause "New" or "Revised" License
58 stars 129 forks source link

readme



The Distributed Generation Market Demand (dGen) Model

Documentation

Get Your Tools

Install Docker for (Mac) or (Windows)

Windows users:

Download Code

Users need to fork a copy of the dGen repo to their own private github account.

Next, clone the forked repository to your local machine by running the following in a terminal/powershell/command prompt: $ git clone https://github.com/<github_username>/dgen.git

Running and Configuring dGen

A. Create Environment

After cloning this repository and installing (and running) Docker as well as Anaconda, we'll create our environment and container:

  1. Depending on directory you cloned this repo into, navigate in terminal to the python directory (/../dgen/python) and run the following command:

$ conda env create -f dg3n.yml

  1. This command will create a container with PostgreSQL initialized.

$ docker run --name postgis_1 -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -d mdillon/postgis

$ docker run --name postgis_1 -p 5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -d mdillon/postgis

To setup another docker container with a different database you can run: $ docker run --name postgis_2 -p 7000:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -d mdillon/postgis where 7000 can be any port number not already in use.

  1. Connect to our postgresql DB. In the command line run the following:
   $ docker exec -it <container id> psql -U postgres
   $ postgres=# CREATE DATABASE dgen_db;

Notes:

B. Download data (agents and database):

Download data by navigating to https://data.openei.org/submissions/1931 and clicking the 'model inputs' tab. Make sure to unzip any zipped files once downloaded. Note, the 13.5 GB dgen_db.sql.zip file contains all of the data for national level runs. We recommend starting with the database specific to the state or ISO region you're interested in.

For example, if you want to simulate only California then navigate to the 'ca_final_db' folder and download the dgen_db.sql file.

You will also need to download and unzip the agent files "OS_dGen_Agents.zip", making sure the use the correct agent file corresponding to the scenario you'd like to run (e.g. commercial agents for California).

Windows Users

We recommend using Powershell. If you don't have UNIX commands enabled for command prompt/powershell then you'll need to install Cygwin or QEMU to run a UNIX terminal.

In Powershell run the following (replace 'path_to_where_you_saved_database_file' below with the actual path where you saved your database file):

   $ docker cp /path_to_where_you_saved_data/dgen_db.sql <container id>:/dgen_db.sql
   $ docker exec -i <container id> psql -U postgres -d dgen_db -f dgen_db.sql

Mac Users

In a new terminal widnow run the following (make sure to replace 'path_to_where_you_saved_database_file' below with the actual path where you saved your database file):

$ cat /path_to_where_you_saved_data/dgen_db.sql | docker exec -i <container id> psql -U postgres -d dgen_db

Notes:

Troublshooting Container/Database Issues:

C. Create Local Server:

Once the database is restored (it will take some time), open PgAdmin and create a new server. Name this whatever you want. Input "localhost" (or 127.0.0.1) in the host/address cell and "postgres" in both the username and password cells. Upon refreshing this and opening the database dropdown, you should be able to see your database.

D: Activate Environment

Activate the dg3n environment and launch spyder by opening a new terminal window and run the following command:

   $ conda activate dg3n
   $ (dg3n) spyder

Notes:

E: Configure Scenario

  1. Open the blank input sheet located in dgen_os/excel/input_sheet_v_beta.xlsm (don't forget to enable macros!). This file defines most of the settings for a scenario. Configure it depending on the desired model run and save a copy in the input_scenarios folder, i.e. dgen_os/input_scenarios/my_scenario.xlsm.

See the Input Sheet Wiki page for more details on customizing scenarios.

  1. In the python folder, open pg_params_connect.json and configure it to your local database. If you didn't change your username or password settings while setting up the docker container, this file should look like the below example:
   {    
    "dbname": "<insert_database_name>",
    "host": "localhost",
    "port": "5432",
    "user": "postgres",
    "password": "postgres"
   }

The cloned repository will have already initialized the default values for the following important parameters:

F: Run the Model

Open dgen_model.py in the Spyder IDE and hit the large green arrow "play button" near the upper left to run the model.

Or, launch python from within the dg3n environment and run: $ python dgen_model.py

Notes:

Saving Results:

  1. To backup the whole database, including the results from the completed run, please run the following command in terminal after changing the save path and database name:

$ docker exec <container_id> pg_dumpall -U postgres > /../path_to_save_directory/dgen_db.sql

  1. To export just the "agent_outputs" table, simply right click on this table and select the "Import/Export" option and configure how you want the data to be saved. Note, if a save directory isn't specified this will likely save in the home directory.

Notes: