Package: urbanopt-ditto-reader
urbanopt-ditto-readerEnhancement of URBANopt™ GeoJSON that can be consumed by DiTTo readerMore detailed documentation is available on theURBANopt documentation pageInstallation Pre-requisitesPython >=3.8Requires Python 3.10 if using via the URBANopt CLI.Installationpip install urbanopt-ditto-readerRunning the converterYou are expected to have an existing URBANopt project dir with successful simulations of electrical network components before using this package.Use the included Command Line Interface:ditto_reader_cli -hFor help text in the terminal:ditto_reader_cli run-opendss -hExample command to run the ditto-reader:ditto_reader_cli run-opendss -s <ScenarioFile> -f <FeatureFile>Or build and use a config file (not necessary if using flags like the above example):ditto_reader_cli run-opendss -c urbanopt_ditto_reader/example_config.jsonIf you are using your own config.json file, use the following fields:"urbanopt_scenario_file": Required, Path to scenario csv file"urbanopt_geojson_file": Required, Path to feature json file"equipment_file": Optional, Path to custom equipment file. If not specified, the 'extended_catalog.json' file will be used"opendss_folder": Required, Path to dir created by this command, holding openDSS output"use_reopt": Required, Boolean (True/False) to analyze reopt data, if it has been provided"start_date": Optional, String, Indicates the start date of the simulation. Uses format "YYYY/MM/DD""start_time": Optional, String, Indicates the start time of the simulation. Uses format
"HH:MM:SS".
The start_date and
start_time are concatenated to get the timestamp (using format "YYYY/MM/DD HH:MM:SS") for the config
file that is cross referenced with the timestamps in the
SCENARIO_NAME/opendss/profiles/timestamps.csv file created from profiles in
SCENARIO_NAME/FEATURE_ID/feature_reports/feature_report_reopt.csv if use_reopt is true and
SCENARIO_NAME/FEATURE_ID/feature_reports/default_feature_report.csv if use_reopt is false. It assumes start_time to be 00:00:00 if start_date is found but no
start_time. It runs the entire year if timestamp not found."end_date": Optional, String, Indicates the end date of the simulation. Uses format "YYYY/MM/DD""end_time": Optional, String, Indicates the end time of the simulation. Uses format "HH:MM:SS".
The end_date and end_time are concatenated to get the timestamp (using format
"YYYY/MM/DD HH:MM:SS") for the config file and is cross referenced with the timestamps in the
SCENARIO_NAME/opendss/profiles/timestamps.csv file created from profiles in
SCENARIO_NAME/FEATURE_ID/feature_reports/feature_report_reopt.csv if use_reopt is true and
SCENARIO_NAME/FEATURE_ID/feature_reports/default_feature_report.csv if use_reopt is false. It assumes end_time to be 23:00:00 if end_date is found but no end_time. It runs the entire year if timestamp not found."timestep": Optional, Float number of minutes between each simulation. If smaller than timesteps (or not an even multiple) provided by the reopt feature reports (if use_repot is true), or urbanopt feature reports (if use_reopt is false), an error is raised"upgrade_transformers": Optional, Boolean (True/False). If true, will automatically upgrade transformers that are sized smaller than the sum of the peak loads that it serves. Does not update geojson file - just opendss output filesIf either start_time and end_time are invalid or set to None, the simulation will be run for all timepoints provided by the reopt simulation (if use_reopt is true) or urbanopt simulation (if use_reopt is false)Developer installationClone the repository:git clone https://github.com/urbanopt/urbanopt-ditto-reader.gitChange directories into the repository:cd urbanopt-ditto-readerAs general guidance, we recommend using virtual environments to avoid dependencies colliding between your Python projects.venvis the Python native solution that will work everywhere, though other options may be more user-friendly.Some popular alternatives are:pyenvandthe virtualenv pluginwork together nicely for Linux/Mac machinesvirtualenvminicondaActivate pre-commit (only once, after making a new venv):pre-commit installRuns automatically on your staged changes before every commitUpdate pip and setuptools:pip install -U pip setuptoolsInstall the respository with developer dependencies:pip install -e .[dev]To check the whole repo, runpre-commit run --all-filesSettings and documentation links for pre-commit and ruff are in .pre-commit-config.yaml and pyproject.tomlReleasingIncrement the version in pyproject.toml. Usesemantic versioning. When a new release is made in GitHub, aworkflowautomatically publishes to PyPI.