Quick Start¶

Installation¶

pip install cimhub_opendss

Environment Setup¶

Two environment variables must be set before importing any CIM objects:

import os
os.environ['CIMG_USE_UNITS'] = 'TRUE'    # enable CIMUnit wrappers
os.environ['CIMG_CIM_PROFILE'] = 'cimhub_2026'

Or set them in your shell before running Python:

export CIMG_USE_UNITS=TRUE
export CIMG_CIM_PROFILE=cimhub_2026

Roundtrip in 4 Lines¶

from cimhub_opendss.importer.dss_to_cim import dss_to_cim
from cimhub_opendss.exporter.cim_to_dss import cim_to_dss

feeder = dss_to_cim("/path/to/Master.dss")
cim_to_dss(feeder, "/path/to/output/")

The output directory will contain Master.dss and one .dss file per component type.

Validation¶

Run the IEEE 13-bus roundtrip integration test:

uv run pytest cimhub_opendss/tests/test_ieee13_roundtrip.py -vs

This imports the IEEE 13-bus model to CIM, exports back to DSS, solves both with OpenDSS, and compares total power and bus voltages. Current accuracy is within 0.14% on active power (4.4 kW on a 3230 kW system).