Usage Examples

To run URBANopt^™, first follow the installation instructions.

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. There are 5 main commands of the CLI: create, run, process, visualize, opendss, and delete.

Important Notes

Keep the project directory path short to avoid an error due to long paths, especially while running on Windows. For more information on this error, refer to known issues.
We recommend calling all URBANopt commands from outside the project folder you created, using relative or absolute paths to the relevant files.

URBANopt CLI Usage Examples

1. Create Project

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 using the default geometry workflow with urban-geometry-creation-zoning measure, and downloads related weather files and detailed models to the appropriate directories.

Users can add a subcommand to use an alternate geometry creation workflow. The following alternate geometry methods can be used:

Createbar

This uses the create_bar_from_building_type_ratio measure to create building geometry.
```
  uo create --project-folder --createbar <path/to/PROJECT_DIRECTORY_NAME>
```
Floorspace

This creates building geometry from floor plans with stub space types drawn using FloorSpaceJS.
```
  uo create --project-folder --floorspace <path/to/PROJECT_DIRECTORY_NAME>
```
For more details on these geometry workflows, refer to geometry_workflows.
Residential Buildings

As of version 0.4.0, URBANopt support a workflow that combines commercial building types and residential building types (Single-family Detached only for now, Single-family Attached and Multifamily will be included in a future release). 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>
```
For more information on residential building support, visit the residential buildings page.
Empty Project

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 energyplus.net/weather.
Overwrite 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:
```
  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. Create Scenario CSV File

First put your FeatureFile in the root of the project directory you just created, or use the provided example feature file: example_project.json.
Create a ScenarioFile for each mapper contained in the project directory by running the following command:
```
 uo create --scenario-file <path/to/FEATUREFILE.json>
```
The resulting CSV files will contain a mapper for each feature in the FeatureFile to the particular scenario mapper.

Single Feature

To create a ScenarioFile for a single Feature, specify the Feature_ID in the arguments as shown here:
```
 uo create --scenario-file <path/to/FEATUREFILE.json> --single-feature <FEATURE_ID>
```
REopt Functionality

If you wish to include REopt Lite post-processing, you will need to create a scenario CSV file with additional information with the following command:
```
 uo create --reopt-scenario-file <path/to/EXISTING_SCENARIO_FILE.csv>
```
This command will create a new scenario CSV (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.

Customizations

In addition to the CLI methods, you can write your own mapper file for your own specific use case as needed, as well as make your own ScenarioFile by copying the structure of an example file. You may also make edits to the ScenarioFiles to mix and match mappers.

3. Run project

Simulate energy usage of each feature or for a single Feature by specifying the appropriate ScenarioFile with the following command:
```
 uo run --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>
```
REopt Functionality

To simulate energy usage for a scenario that will require additional REopt Lite post-processing, run this command instead:
```
 uo run --reopt --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>
```
Note that 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 above command.

4. Post-process project

To post-process the simulated features into a Scenario report, call the CLI process command using default as the type:
```
 uo process --<TYPE> --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>
```
Valid types are: default, opendss, reopt-scenario, reopt-feature

REopt Functionality

If you intend to post-process with REopt Lite (i.e. using reopt-scenario, reopt-feature), please now refer to the instructions outlined in REopt Post-Processing. Otherwise, post-process simulated features into a Scenario report by using default as the type:
```
 uo process --<TYPE> --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>
```
OpenDSS Functionality

If you intend to post-process OpenDSS results, use opendss as the type:
```
 uo process --<TYPE> --feature <path/to/FEATUREFILE.json> --scenario <path/to/SCENARIOFILE.csv>
```
For more information on the OpenDSS workflow, visit the OpenDSS page.

SQL output

Post-processing also generates a database file of aggregate energy use (all buildings included) at each hour for the named scenario.

The database file is called default_scenario_report.db and be found in the scenario directory. The relevant table is named ReportData:

TimeIndex Year Month Day Hour Minute Dst ReportDataDictionaryIndex Value

Integer Var Var Var Var Var Var Integer Integer

10 = Electricity 1382 = Gas Amount (J)

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

5. Visualize project

Once a project has been post-processed, the results can be visualize either at the scenario level, or for each individual feature of a scenario.

To visualize and compare the post-processing results for all scenarios, run the following command:
```
 uo visualize --scenario <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 --feature <path/to/SCENARIOFILE.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.

Delete an outdated Scenario:

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

Workflow Details

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

workflow_diagram

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

scenario_mapper