To run URBANopt, first install the project dependencies and the URBANopt Command Line Interface.

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 <command> --help

  1. Create a project folder in your current directory using:

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

    This creates a project folder containing the example project, and downloads related weather files and detailed models to the appropriate folders.

    Create an empty base project folder by using:

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

    This creates project folder without an example FeatureFile and an empty weather folder. You can download weather files and add to this folder from

    Overwrite an existing folder by using:

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

    This deletes anything in the named folder and creates a fresh project directory. Can be combined with -e to overwrite a directory with a new empty URBANopt project directory.

  2. Put your FeatureFile in the root of the folder you just created, or use the provided example.
  3. We recommend calling all URBANopt commands from outside the project folder you created, using relative or absolute paths to the relevant files.
  4. Create ScenarioFiles for all Features in the FeatureFile based off the example mappers using:

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

    Or create a ScenarioFile for a single Feature by specifying the Feature_ID in the arguments.

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

    Or create a ScenarioFile with additional REopt information to enable running and post-processing with REopt data.

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

    You may write your own mapper file for your own specific use case as needed, as well as make your own ScenarioFile by hand. You may also make edits to the ScenarioFiles to mix and match mappers.

  5. Simulate energy usage of each feature or for a single Feature by specifying the appropriate ScenarioFile by using:

     uo run --feature <path/to/FEATUREFILE> --scenario <path/to/SCENARIOFILE>
  6. Simulate energy usage for a scenario with additional REopt capability. Run this simulation to enable REopt post-processing (see below for details).

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

    Note that there is a runner.conf file automatically created in the project folder. This file is 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 above command.

  7. Post-process simulated features into a Scenario report by using:

     uo process --<TYPE> --feature <path/to/FEATUREFILE> --scenario <path/to/SCENARIOFILE>

    Valid TYPEs are: default, opendss, reopt-scenario, reopt-feature

  8. Delete an outdated Scenario run by using:

     uo delete --scenario <path/to/SCENARIOFILE>

Workflow Details

The figure below describes the workflow that takes place for the run and post_process calls.


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