Link Search Menu Expand Document

To run URBANopt™, first follow the installation instructions to install the URBANopt command line interface (CLI) and all of its dependencies.

Once the CLI is installed, help is available by typing uo --help from the command line. Detailed help for each command can be found with uo [the command name] --help. The main CLI commands are: create, run, process, visualize, opendss, and delete.

Before you start, think about the capabilities and analyses you want to utilize and setup your project accordingly. The best way to start is to use the example project made with the CLI. Once you are familiar with the commands you can customize your project.

Important Notes

Keep the project directory path short to avoid errors related to long paths, especially when running on Windows. For more information on this error, refer to the known issues section.

We recommend calling all URBANopt commands from outside of the project you created, using relative or absolute paths to the relevant files.


Steps

The overall URBANopt process is shown in the graphic below. UO process steps image

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.

1. Create Project

Set up the project directory structure and example files

image of an open directory folder and its contents

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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

Other Options

  • 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>
  • 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>

2. Set up Scenario

Assign a Scenario Mapper to each feature
Configure additional settings

image of CSVs being inserted into a directory folder

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.

  • 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>
    1. To run a REopt scenario you will need an internet connection so the REopt™ Gem can access the REopt Lite API.
    2. Obtain an API key from the NREL Developer Network to use the REopt Lite 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 assumption files to features. Use this Scenario CSV File going forward in future steps. </p>
      uo create --reopt-scenario-file <path/to/EXISTING_SCENARIO_FILE.csv>
    4. Configure your REopt assumptions. Two example REopt Lite assumption 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 Lite API documentation and can be customized to your specific project needs. Though 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 Lite 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 and ground-mount).

    Visit the REopt page for more details on using REopt with URBANopt.

Other Options

  • 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>
  • 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.

    diagram showing assigment of different mapper classes to different features
  • 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.

3. Run Scenario

Simulate Energy Usage of each FeatureFile mapped in a Scenario CSV File

image of a run icon

Expand the sections below to learn more about running a basic scenario and running a REopt-enabled project.

Config File—there is a runner.conf file automatically created in the project folder. This file can be used to configure the number of features to process in parallel as well as a few other parameters. Make edits to this file prior to running the 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>
  • Or

  • To simulate energy usage for a scenario with REopt-enabled functionality, add the --reopt flag to the command to extend the Scenario CSV File with REopt functionality:

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

4. Post-Process Scenario

Aggregate the results of the simulation across the scenario

icon of a report file

Expand the sections below to choose the option that is right for your project.

You must run the default post-processing command before running any additional analyses such as OpenDSS and DES, or running the REopt optimization and post-processing the results.

  • 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

  • REopt Lite 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 Lite 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.

    Visit the REopt Workflow page for more details on using REopt.

    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 REoptLite 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
  • 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.

  • 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>

Additional Capabilities (Optional)

Add Electrical Distribution or Distributed Thermal Systems Analysis to your Scenario

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

  • 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. Visit the OpenDSS Installation page to install OpenDSS and URBANopt DiTTo Reader.

    Once you have installed Python and urbanopt-ditto-reader, 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.

    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`

      • --equipment: Path to custom equipment file. View the OpenDSS page for more info.
      • --start-time: Beginning of the period for OpenDSS analysis. Defaults to beginning of simulation time Format: "YYYY/MM/DD HH:MM:SS" (use quotes).
      • --end-time: End of the period for OpenDSS analysis. Defaults to end of simulation time. Format "YYYY/MM/DD HH:MM:SS" (use quotes).
      • --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 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>
  • 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. Additonal 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.
  • 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

5. Plot Results

Generate visualizations at the feature level and scenario level.

icon of a chart

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.

  • 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.

  • 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.


URBANopt, Copyright (c) 2019-2021, Alliance for Sustainable Energy, LLC, and other contributors. All rights reserved.