sympheny-toolbox 1.0.0

Lightweight Python wrapper for the Sympheny SaaS API to automate common workflows.

Sympheny Toolbox

A lightweight Python wrapper for the Sympheny SaaS API to automate common workflows — create scenarios, run optimizations, manage variants, and more.

Install

pip install sympheny-toolbox

Requires Python 3.11+.

Authentication

Create a .properties file with your Sympheny credentials:

username=[e-mail]
password=your-password

Then load and connect:

from sympheny_toolbox.sympheny import Sympheny
from sympheny_toolbox.utils import load_creds_basic

username, password = load_creds_basic("creds.properties")
s = Sympheny(username, password)

# Use is_dev=True for the dev environment

Tip: Don't commit credential files — use a secrets manager or .gitignore.

Usage

Find projects, analyses, and scenarios

project = s.find_project("My Project")
analysis = s.find_analysis("My Analysis", project["projectGuid"])
scenario = s.find_scenario("Base", analysis["analysisGuid"])

Create a scenario from Excel

scenario_guid = s.create_scenario_from_excel(
    excel_path="scenario.xlsx",
    scenario_name="demo",
    analysis_guid=analysis_guid,
)
print(s.scenario_url(scenario_guid))

Create scenario variants from Excel

variants = s.create_variants_from_excel(
    excel_path="variants.xlsx",
    master_scenario_id=scenario_guid,
)

Generate and read an input file

from sympheny_toolbox.utils import load_sheet_from_presigned_url

url = s.generate_input_file(scenario_guid)
rows = load_sheet_from_presigned_url(url, sheet="Conversion Techs")

Execute a scenario

s.execute_scenario(scenario_guid)

Create an EnyMap scenario

scenario_guid = s.create_scenario_enymap(
    scenario_name="enymap_demo",
    analysis_id=analysis_guid,
    techs=["PV", "HEAT_PUMP"],
    demands=["ELECTRICITY", "SPACE_HEATING"],
    imports=["ELECTRICITY"],
    exports=["HEAT_AMBIENT"],
    poly=[[lon, lat], ...],
)

Available EnyMap options are defined in sympheny_toolbox.enymap:

Parameter	Options
techs	PV, HEAT_PUMP, GAS_BOILER, CHILLER, BATTERY, HOT_WATER_STORAGE
demands	HOT_WATER, SPACE_HEATING, ELECTRICITY, COOLING
imports	ELECTRICITY
exports	HEAT_AMBIENT, COOLING