---

Steps

The overall URBANopt process is shown in the graphic below.

Read through each section below for more information on each step of the process—including CLI command examples—and for details on the different workflows available.

Expand the sections below and choose the option that is right for your project. Most of the options will create both a project directory structure and example project files that will allow you to try out the additional commands. Visit the example project page to learn more about the example project. You can also watch a tutorial video on Project Creation and GeoJSON File Overview.

• Use the default workflow

  Use the command below to create a default project:

  uo create --project-folder <path/to/PROJECT_DIRECTORY_NAME>

  This creates a project folder containing the example project using the default geometry workflow with urban-geometry-creation-zoning measure, and downloads related weather files and detailed models to the appropriate directories.

  For more details on the various geometry workflows, refer to the geometry_workflows page.

• Use Createbar geometry workflow

  This project uses the create_bar_from_building_type_ratio measure to create building geometry.

  uo create --create-bar --project-folder  <path/to/PROJECT_DIRECTORY_NAME>

  For more details on the various geometry workflows, refer to the geometry_workflows page.

• Use Floorspace geometry workflow

  This creates building geometry from floor plans with stub space types drawn using FloorSpaceJS.

  uo create --floorspace --project-folder  <path/to/PROJECT_DIRECTORY_NAME>

  For more details on the various geometry workflows, refer to the geometry_workflows page.

• Include Residential buildings in your project

  As of version 0.4.0, URBANopt supports a workflow that combines commercial building types and residential building types (Single-family Detached only for now, with beta testing code for Single-family Attached and Low-rise Multifamily).

  To create a project that contains all files required to run this combined workflow, add the --combined option to the create command:

    uo create --combined --project-folder <path/to/PROJECT_DIRECTORY_NAME>

  The rest of the CLI commands are the same as for the default workflow. Make sure that you use and inspect the example_project_combined.json FeatureFile in your project directory to see an example of a residential feature specification (feature IDs 14, 15, and 16) and the additional fields required for residential building types.

  Residential building energy models in URBANopt are created using the OpenStudio-HPXML workflow. Visit the Residential Workflows page to learn more.

• Include PV features in your project

  As of version 0.6.3, URBANopt supports community photovoltaic and ground mount photovoltaic features.

  To create a PV-enabled project add the --photovoltaic option to the create command:

   uo create --photovoltaic --project-folder <path/to/PROJECT_DIRECTORY_NAME>

  The rest of the CLI commands are the same as for the default REopt workflow. Inspect the example_project_with_PV.json FeatureFile in your project directory to see examples of community photovoltaic and ground mount photovoltaic features.

  Visit the Photovoltaic Workflows page to learn more.

• Include OpenDSS functionality in your project

  In order to use the OpenDSS functionality successfully, the FeatureFile should contain Electrical Connectors and Junctions. Use the command below to create an example project containing a FeatureFile with electrical network defined within it (example_project_with_electric_network.json). You can also use your own Feature File as long as the electrical infrastructure is defined and connected to the buildings accordingly.

    uo create --electric --project-folder <path/to/PROJECT_DIRECTORY_NAME>

  View the OpenDSS section under Additional Capabilities below for more details on the OpenDSS functionality.

• Include RNM functionality in your project

  In order to use the RNM functionality successfully, the FeatureFile should contain streets as well as the location of the primary electrical substation. Use the command below to create an example project containing a FeatureFile with streets defined within it (example_project_with_streets.json). You can also use your own Feature File that includes streets.

    uo create --streets --project-folder <path/to/PROJECT_DIRECTORY_NAME>

  View the RNM section under Additional Capabilities below for more details on the RNM functionality.

• Include DISCO functionality in your project

  In order to use the DISCO functionality successfully, the FeatureFile should contain Electrical distribution system features. The project directory should also contain a cost database input file and a technical catalog input file to be used by the DISCO analysis. Use the command below to create an example project containing a FeatureFile with electrical network defined within it (example_project_with_electric_network.json) as well as a disco folder including the necessary catalog input files. You can also use your own Feature File that includes an electric network.

    uo create --disco --project-folder <path/to/PROJECT_DIRECTORY_NAME>

  View the DISCO section under Additional Capabilities below for more details on the DISCO functionality.

Other Options

• Create an empty project directory structure

  This option creates a project directory structure without an example FeatureFile or weather files. You can download weather files and add to this folder from the EnergyPlus™ Website.

  uo create --empty --project-folder <path/to/PROJECT_DIRECTORY_NAME>

• Overwrite an existing project

  By default, the CLI will abort if the project directory being created already exists. To overwrite an existing folder, use the --overwrite option. This deletes anything in the named folder and creates a fresh project directory. This command can be combined with the -e option to overwrite a directory with a new empty URBANopt project directory.

  uo create --overwrite --project-folder <path/to/PROJECT_DIRECTORY_NAME>

• Update an existing project to a more recent version of URBANopt

  The update function can be used to update an existing URBANopt project to the currently installed URBANopt CLI version. This process will overwrite the existing URBANopt files and folders in the new project folder with the updated ones. If you have made modifications to the following files in your existing folder, you will need to reinstate these modifications in the new project folder:

  • Gemfile
  • validation_schema.yaml
  • runner.conf
  • Example Feature File
  • mappers folder
  • osm_building folder
  • weather folder
  • visualization folder
  • residential folder
  • measures folder
  • resources folder
  • xml_building folder in case of a residential project
  • reopt folder in case of a REopt project
  • opendss folder in case of an OpenDSS project
  • disco folder in case of a DISCO project

  To update the project, specify the existing project folder name and location for the updated URBANopt project:

  uo update --existing-project-folder <name of existing project> --new-project-directory <location/to/new_urbanopt_example_project>

If you are not using an example project, ensure that your FeatureFile is in the root of the project directory. If you are using an example project, an example feature file is provided for you.

You can also view the tutorial video on Creating and Running Scenarios.

• Create a Scenario CSV File for each mapper

  The following command will create a ScenarioFile for each mapper contained in the project directory. The resulting CSV files will map all features in the FeatureFile to the particular scenario mapper. The scenario mappers currently included in URBANopt are listed above. Visit the Scenarios page to learn more about each scenario mapper.

  uo create --scenario-file <path/to/FEATUREFILE.json>

• Enable REopt™ Functionality
  1. To run a REopt scenario you will need an internet connection so the REopt™ Gem can access the REopt API.
  2. Obtain an API key from the NREL Developer Network to use the REopt API. Copy and paste your key as an environment variable named GEM_DEVELOPER_KEY on your computer. Step-by-step instructions for creating env variables are found in the installation docs for your operating system.

      GEM_DEVELOPER_KEY = '<insert your NREL developer key here'>

  3. Extend the Scenario CSV File with REopt information. After following the instructions above to create a basic Scenario CSV File for each mapper, use the command below to create a new Scenario CSV File (named REopt_scenario.csv by default) that has an extra column to map assumptions files to features. Use this Scenario CSV File going forward in future steps. The assumptions file listed in the Scenario CSV will be used when performing a REopt feature optimization. By default, this is set to multiPV_assumptions.json. If you'd like to use a different file, open the Scenario CSV file, edit the assumptions file name and save. Your new assumptions file should be saved in the reopt directory within your project directory.

     uo create --reopt-scenario-file <path/to/EXISTING_SCENARIO_FILE.csv>

  4. Configure your REopt assumptions. Two example REopt assumptions files are located in the reopt folder within your project directory: base_assumptions.json and multiPV_assumptions.json. These files follow the format outlined in the REopt API documentation and can be customized to your specific project needs. Through CLI commands, they will be updated with basic information from your Feature and Scenario Reports (i.e. latitude, longitude, electric load profile) and submitted to the REopt API.

     In particular, you will want to make sure that the urdb_label in the assumptions file maps to a suitable utility rate label from the URDB. The label is the last term of the URL of a utility rate detail page (e.g. the label for the rate at https://openei.org/apps/IURDB/rate/view/5b0d83af5457a3f276733305 is 5b0d83af5457a3f276733305).

     Also note that the example reopt/multiPV_assumptions.json file contains an array of PV inputs to allow for the optimization of multiple PV systems at once (e.g. rooftop PV and ground mount PV).

     Unless otherwise configured, the multiPV_assumptions.json file will be used inside the REopt-enabled Scenario CSV for feature-level optimizations, and the base_assumptions.json file will be used for scenario-level optimizations. Both of these files can be found in the reopt directory within the project directory.

     A complete list of input fields—including type, description, and acceptable range—can be retrieved from the REopt API by entering the following URL in your browser:

     https://developer.nrel.gov/api/reopt/stable/help?API_KEY=<insert your NREL developer key here>

  Visit the REopt page for more details on using REopt with URBANopt, or watch the REopt Workflow Tutorial Video.

Other Options

• Create a scenario CSV File for a single Feature

  If you need to run a single feature through the URBANopt process, you will first need to generate a Scenario CSV File containing only that Feature. To accomplish this, specify the Feature_ID in the arguments as shown here:

   uo create --scenario-file <path/to/FEATUREFILE.json> --single-feature <FEATURE_ID>

• Create a mixed Scenario CSV File

  The default process to create a Scenario CSV File for each mapper assigns the same mapper to all Features in the FeatureFile. If you wish to customize the scenario so that features are mapped to different mappers, the best course of action is to first generate the basic Scenario CSV Files for each mapper and then edit them to assign the various mappers.

  The following figure represents how Simulation Mapper Classes can be assigned to different Features from the FeatureFile in the Scenario CSV.

  
• Customize the mappers

  In addition to Scenario mappers included in the URBANopt CLI, you can write your own mapper file for a specific use case. You can also edit the existing mappers in your project directory. Visit the Customizations page to learn about how to customize your URBANopt workflow.

Expand the sections below to learn more about running a basic scenario and running a REopt-enabled project. You can also view the tutorial video on Creating and Running Scenarios.

• Run a basic project

  Simulate the energy usage of each feature in a scenario. Use the following command to specify the appropriate FeatureFile and Scenario CSV File:

   uo run --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>

  Running a simulation is computationally intensive. Each building simulation must be run on one CPU core at a time. To reduce the time spent on computation you may use multiple cores simultaneously to simulate several buildings in your scenario at once. The default is 2 cores, set in the runner.conf file of each project. You may alter this on the fly by including --num-parallel=[i] in the run command above, where [i] is the number of cores you want to use.

  You may also set the num-parallel globally by using an environment variable and not have to adjust the runner.conf file or use the above CLI flag in each project or run. To do this, create an environment variable and set it to the number of cores you want to use: UO_NUM_PARALLEL=7 or other appropriate number.

Expand the sections below to choose the option that is right for your project. You can also watch the tutorial video on Post-Processing Scenarios.

• Post-process general results (default post-processor)

  To post-process the simulated features into a Scenario report, call the CLI process command using the --default flag:

    uo process --default --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>

  Output Files

  The post-process command will aggregate data across all the features in a scenario and generate results files in the scenario results folder:

  1. JSON — a default_scenario_report.json file containing overall results
  2. CSV Timeseries— a default_scenario_report.csv file containing aggregated timeseries data.

  If the scenario is consequently post-processed with another option flag (i.e. --reopt-scenario, --reopt-feature, or --opendss, see sections below), the new data will be appended to the existing results files.

Other Options

• Post-process REopt results

  REopt optimization happens during the post-processing of each scenario, after the scenario is run. Two types of REopt optimization are available:

  1. scenario-level, which optimizes for the aggregate load of the entire district being simulated assuming there is one primary utility meter, and
  2. feature-level, which optimizes each building’s load individually assuming each building is individually metered.

  You may chose to optimize by one or both of these approaches according to your project objectives.

  Note—You will need an internet connection so the REopt™ Gem can access the REopt API.

  To optimize at the scenario-level, use the --reopt-scenario flag:

    uo process --reopt-scenario --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>

  The --reopt-scenario-assumptions-file (or -a) option can be used to specify the path to the assumptions file to use for this optimization. If none is specified, the base_assumptions.json file in the reopt folder of the project directory will be used.

  To optimize at the feature-level, use the --reopt-feature flag:

    uo process --reopt-feature --feature <path/to/FEATUREFILE.json> --scenario <path/to/REoptEnabledSCENARIOFILE.csv>

  For this optimization, the assumptions file is specified per feature in the Scenario CSV file, and is defaulted to the multiPV_assumptions.json file in the reopt folder of the project directory.

  Visit the REopt Workflow page for more details on using REopt, or watch the REopt Workflow Tutorial Video.

  Additional Options:

  the process command can be used with the following additional REopt-related options:

  1. --reopt-resilience: adding this option will include resilience reporting in the REopt optimization
  2. --reopt-keep-existing: the REopt API rate limit (300 API calls per hour) may be reached when processing projects with a large number of features. If that is the case, use this option to continue processing the remaining features after the hour has elapsed.

  You can run the help command to see the full list of options:

    uo process --help

  Output Files

  The REopt optimizations will generate results files in the scenario results folder:

  1. JSON — a scenario_optimization.json file containing overall scenario optimization results, and/or a feature_optimization.json file containing aggregated feature optimization results.
  2. CSV Timeseries— a scenario_optimization.csv file containing REopt aggregated timeseries results for the scenario optimization (REopt:ElectricityProduced:Total(kw), for example) and/or a feature_optimization.csv containing REopt aggregated timeseries results for the feature optimization.
  3. Detailed REopt results— can be found in the scenario_report_reopt_scenario_reopt_run.json inside the scenario results' inner reopt folder. Additionally, individual feature_optimization.json and feature_optimization.csv files can be found in each feature's reopt directory inside the feature's results directory.

  The figure below illustrates the results directory structure.

  
• Post-process OpenDSS results

  To post-process OpenDSS results back into the main Scenario JSON and CSV results files, use the --opendss flag.

  Note— Run this command after you a) post-process the general scenario results and b) run the OpenDSS workflow as described in the Additional Capabilities section below.

    uo process --opendss --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>

  For more information on the OpenDSS workflow, visit the OpenDSS page or watch the OpenDSS Workflow Video Tutorial.

• SQL Database Output File

  In addition to the JSON and CSV output files, a SQL Database file (default_scenario_report.db) containing aggregated energy use across the scenario is also available. The relevant data is in the ReportData table to match the structure of the eplusout.sql file generated for each building by EnergyPlus.

  The ReportData table structure is as follows:

  TimeIndex	Year	Month	Day	Hour	Minute	Dst	ReportDataDictionaryIndex	Value
  Integer	Var	Var	Var	Var	Var	Var	Integer 10 = Electricity; 1382 = Gas	Integer Amount (J)

  Add the --with-database flag to your command to generate this file:

    uo process --default --with-database --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>

Expand the sections below to learn more about optional capabilities available in URBANopt

• OpenDSS Functionality

  OpenDSS is an open-source tool that is popular for simulating electrical distribution systems. The DIstribution Transformation TOol (DiTTo) is an open source and many-to-many conversion tool that has been developed by NREL to simplify converting data between distribution models. Finally, the URBANopt DiTTo Reader package and CLI provide the link between URBANopt and OpenDSS.

  The entire DiTTo-Reader to OpenDSS workflow is available in URBANopt via the opendss URBANopt CLI command.

  Since the DiTTo Reader and OpenDSS functionality is written in Python, additional dependencies will need to be installed if you wish to use this workflow. Run the uo install_python command to install Python and all required dependencies.

  Once you have installed Python and Python-related dependencies with the uo install_python command, you can use the opendss CLI command to access the OpenDSS functionality. You can use the opendss CLI command after you have run the scenario (using a FeatureFile that contains a fully-connected electrical network) and post-process the general results with the --default post-processor. The OpenDSS workflow will use these results files in the processing.

  Watch the OpenDSS Workflow Tutorial Video.

  Step-by-Step of the entire OpenDSS-enabled workflow:

  1. Create an example project with the --electric option or use your own FeatureFile containing electrical network information.
  2. Create the Scenario CSV file and run the project as explained above in Steps 2 and 3. You can run the basic project or the REopt-enabled project.
  3. Post-process the general results with the uo process --default command described above in Step 4. If you have a REopt-enabled project, also post-process the results with the desired REopt post-processor (either --reopt-scenario or --reopt-feature).
  4. Run OpenDSS:

     To run the general OpenDSS workflow, use the following command:

       uo opendss --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>

     To run the REopt-enabled OpenDSS workflow, include the --reopt flag in the command:

       uo opendss --reopt --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>

     In addition to the required `--scenario` and `--feature` options, there are optional options that can be specified, as listed below. You can also run the CLI help command for more information and examples: `uo opendss -h`

     • --rnm: Use RNM-generated DSS files in this analysis.
     • --equipment: Path to custom equipment file. View the OpenDSS page for more info.
     • --start-date: Optional, Beginning date for OpenDSS analysis. Defaults to beginning date of simulation period. Format: YYYY/MM/DD
     • --start-time: Optional, Beginning time for OpenDSS analysis. Defaults to 00:00:00 of start_date if specified, otherwise beginning time of simulation period. Format: HH:MM:SS
     • --end-date: Optional, End date for OpenDSS analysis. Defaults to ending date of simulation period. Format: YYYY/MM/DD
     • --end-time: Optional, Ending time for OpenDSS analysis. Defaults to 23:00:00 of end_date if specified, otherwise ending time of simulation period. Format: HH:MM:SS.
     • --timesteps: Number of minutes per timestep in the OpenDSS simulation.

     Alternatively, a config JSON file can be used to set the OpenDSS options. An example config JSON file is available. Note the key names are slightly different than the CLI option names. This config file can be passed into the CLI command:

       uo opendss --config <path/to/config.json>

  5. Finally, post-process the results with the --opendss post-processor to pull the openDSS results back into the main result files.

       uo process –opendss –feature <path/to/FEATUREFILE.json> –scenario <path/to/SCENARIOFILE.csv>

• DES Functionality

  DES functionality is available in URBANopt CLI version 0.5.2 and above.

  Once a scenario has been run and processed as explained in the sections above, a district thermal simulation can then be run using the output from the URBANopt SDK. While Additional district energy system simulation capabilities will be added in the future, only timeseries simulations of 4th generation district heating & cooling systems are currently available.

  Follow the steps below to configure, create, and run your DES simulation:

  1. Build a system parameters JSON config file from the existing URBANopt processed results:

       uo des_params --sys-param-file <path/to/create/new/sys_params.json> --scenario <path/to/SCENARIOFILE.csv> --feature <path/to/FEATUREFILE.json> --model-type time_series

  2. Create a Modelica model directory and give it a name:

       uo des_create --sys-param <path/to/sys_params.json> --feature <path/to/FEATUREFILE.json> --des-name <path/to/create/new/modelica_dir> --model-type time_series

  3. Run the Modelica simulation:

      uo des_run --model <path/to/modelica_dir>

  For more information, visit the DES Workflow page. Or watch the DES Workflow Tutorial Video.

• RNM Functionality

  RNM functionality is available in URBANopt CLI version 0.6.2 and above.

  Once a scenario has been run and processed as explained in the sections above, an RNM simulation can then be run using the output from the URBANopt SDK.

  To run the RNM workflow, use the following command:

    uo rnm --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>

  The result files scenario_report_rnm.json and feature_file_rnm.json can be found in the scenario directory. Additional RNM outputs are in the rnm-us/results directory.

  Additional options that can be used with the rnm command are:

  • --reopt: Use this option to use REopt results in the RNM analysis. In order to do so, the scenario must first be post-processed with the REopt feature optimization option (`--reopt-feature`)
  • --extended-catalog: Use this option to specify the path to the extended electrical catalog. If this option is not included, the default catalog will be used
  • --average-peak-catalog: Use this option to specify the path to the average peak catalog. If this option is not included, the default catalog will be used.
  • --opendss: Use this option to request that an OpenDSS-compatible electrical database JSON file be created.

  Once the RNM Workflow is run, the resulting DSS files can be processed with OpenDSS, if desired. View the OpenDSS section for command details.

  View the RNM Workflow page for more info. Or watch the RNM Workflow Tutorial Video.

• DISCO Functionality

  DISCO functionality is available in URBANopt CLI version 0.9.0 and above.

  To access DISCO functionality, first create a project with the --disco flag. This will create an example project with electrical distribution network features in the feature file as well as the required default DISCO files in a folder named disco within the project folder. Once a project scenario has first been run and processed with the default post-processor, then run through the OpenDSS workflow and processed with the OpenDSS post-processor, a DISCO analysis can finally be run.

  To run the DISCO workflow, use the following command:

    uo disco --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>

  Additional options that can be used with the disco command are:

  • --cost_database: Use this option to specify the file name of a custom cost database file. If omitted, the default cost database found in the disco folder will be used
  • --technical_catalog: Use this option to specify the file name of a custom technical catalog file. If omitted, the default technical catalog found in the disco folder will be used

  View the DISCO Workflow page for more info.

• Validate EUI Results

  URBANopt provides a method to validate the energy use intensity (EUI) results from your full year simulation against a relatively wide range of potential EUI values. This can be used to confirm that your simulation results are within the right ballpark. Note: this does not guarantee that no errors or inaccuracies are present, it just helps perform an initial check on simulation output results. The schema file is included in the project_dir and can be customized if your buildings are unusual.

  This functionality requires the --scenario_file and --feature_file options to be specified.

  Currently only supports validating eui, and requires the path to the validation_schema that you are using. An example validation schema can be found in the project directory.

    uo validate --eui validation_schema.yaml --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>

  Optionally, you can specify the units to work with. Valid options are SI and IP; defaults to IP if not specified.

    uo validate --eui validation_schema.yaml --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv> --units IP

  For more information, watch the Visualization and Validation Tutorial Video.

Once one or more scenarios have been run and post-processed, the results can be visualized either at the scenario level, or for each individual feature within a single scenario.

• Visualize and compare all Scenarios

  Use the following command to visualize and compare the post-processing results for all scenarios:

     uo visualize --feature <path/to/FEATUREFILE.json>

  The resulting visualizations can be viewed in the scenario_comparison.html file in the run folder.

• Visualize and compare all Features within a Scenario

  To visualize and compare the post-processing results for all features in a particular scenario:

     uo visualize --scenario <path/to/scenario.csv>

  The resulting visualizations can be viewed in the feature_comparison.html file in the scenario folder.

Note—You need to run the default post-process command before visualizing the results.

For more information, watch the Visualization and Validation Tutorial Video.

---