Skip to content

urbanopt/urbanopt-cli

Repository files navigation

CLI build status
Core-gem Coverage Status
Geojson-gem Coverage Status
Reopt-gem Coverage Status
Reporting-gem Coverage Status
RNM-gem Coverage Status
Scenario-gem Coverage Status
Example-project CI Coverage Status

URBANopt CLI

This is the command line interface (CLI) for the URBANopt™ SDK.

Installation (Using Ruby)

Add this line to your application's Gemfile:

gem 'urbanopt-cli'

And then execute:

bundle

Or install it yourself with:

gem install urbanopt-cli

Installation (Using Installer)

The UrbanOpt installer is an alternate way to install the UrbanOpt CLI that also includes Ruby 2.7.2 and the OpenStudio SDK. Below are installation instructions for each platform.

Linux (Ubuntu 18.04)

Download the .deb package.

sudo apt update
sudo apt install ./UrbanOptCLI-0.3.1.b6f118d506-Linux.deb

This will install to /usr/local/ directory. e.g. /usr/local/urbanopt-cli-0.3.1/

To run the UrbanOpt CLI, first run the setup-env.sh script that generates environmental variables and stores these in env_uo.sh in your home directory.

/usr/local/urbanopt-cli-0.3.1/setup-env.sh
. ~/.env_uo.sh

When launching new shell terminals run . ~/.env_uo.sh to setup the environment. 

Mac OSX (>= 10.12)

Download the .dmg package.

Use the GUI installer and choose a directory to install. Once installed, open a terminal and run the provided setup script. The setup-env.sh generates env variables and stores them in a file .env_uo.sh in your home directory.

/Applications/UrbanOptCLI_0.3.1/setup-env.sh
. ~/.env_uo.sh

When launching new shell terminals run . ~/.env_uo.sh to setup the environment. 

Windows (64-bit Windows 7 – 10)

Download the .exe installer.

Use the GUI installer and choose a directory to install. Once installed, open a terminal (Powershell, Windows CMD and GitBash are supported) and run the provided setup script for that shell (below are the setup scripts for each respective shell environment).

Bash (or GitBash for Windows)

c:/urbanopt-cli-0.3.1/setup-env.sh
. ~/.env_uo.sh

Powershell

c:\urbanopt-cli-0.3.1\setup-env.ps1
. ~\.env_uo.ps1

Windows Command Prompt

c:\urbanopt-cli-0.3.1\setup-env.bat
%HOMEPATH%\.env_uo.bat

When launching new shell terminals run the correct environment config to setup the environment. 

Usage

For help text in your terminal, type:

uo --help

Create a project folder:

uo create --project-folder <FOLDERNAME>

Overwrite an existing project folder:

uo create --overwrite --project-folder <FOLDERNAME>

Create an empty project folder without the example files:

uo create --empty --project-folder <FOLDERNAME>

Create ScenarioFiles from a FeatureFile using MapperFiles:

uo create --scenario-file <FEATUREFILE>

Create a ScenarioFile using only a specific FEATURE_ID from a FEATUREFILE:

uo create --scenario-file <FEATUREFILE> --single-feature <FEATURE_ID>

Create a REopt ScenarioFile from an existing ScenarioFile:

uo create --reopt-scenario-file baseline_scenario.csv

Run URBANopt energy simulations for each feature in your scenario:

uo run --scenario <SCENARIOFILE> --feature <FEATUREFILE>

Run URBANopt energy simulations for each feature in your scenario, with REopt functionality included:

uo run --reopt --scenario <SCENARIOFILE> --feature <FEATUREFILE>

Post-process simulations for a full scenario:

uo process --<TYPE> --scenario <SCENARIOFILE> --feature <FEATUREFILE>
  • Valid TYPEs are: default, opendss, reopt-scenario, reopt-feature, reopt-resilience, disco

Delete a scenario you have already run:

uo delete --scenario <SCENARIOFILE>

Installed CLI version:

uo --version

Current Python Dependencies

Python dependencies are currently versioned as follows:

Python Package Version
urbanopt-ditto-reader 0.6.3
NREL-disco 0.5.0
geojson-modelica-translator 0.6.0
ThermalNetwork 0.2.3

Development

To install this gem onto your local machine, clone this repo and run bundle exec rake install. If you make changes to this repo, update the version number in lib/version.rb in your first commit. When ready to release, follow the documentation.