Metadata-Version: 2.4
Name: sympheny-toolbox
Version: 1.2.0
Summary: Lightweight Python wrapper for the Sympheny SaaS API to automate common workflows.
Keywords: sympheny,energy,optimization,urban-planning,sustainability
License-Expression: Apache-2.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: jproperties>=2.0.0,<3
Requires-Dist: openpyxl>=3.0.0,<4
Requires-Dist: pandas>=2.0.0,<4
Requires-Dist: requests>=2.0.0,<3
Requires-Python: >=3.11, <4
Project-URL: Homepage, https://www.sympheny.com
Project-URL: Repository, https://github.com/urban-sympheny/sympheny-toolbox.git
Project-URL: Issues, https://github.com/urban-sympheny/sympheny-toolbox/issues
Description-Content-Type: text/markdown

[![PyPI - Version](https://img.shields.io/pypi/v/sympheny-toolbox.svg)](https://pypi.org/project/sympheny-toolbox)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sympheny-toolbox.svg)](https://pypi.org/project/sympheny-toolbox)

# Sympheny Toolbox

A lightweight Python wrapper for the [Sympheny](https://www.sympheny.com) SaaS API to automate common workflows — create scenarios, run optimizations, manage variants, and more.

## Install

```bash
pip install sympheny-toolbox
```

Requires **Python 3.11+**.

## Authentication

Create a `.properties` file with your Sympheny credentials:

```properties
username=you@example.com
password=your-password
```

Then load and connect:

```python
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

```python
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

```python
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

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

### Generate and read an input file

```python
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

```python
s.execute_scenario(scenario_guid)
```

### Create an EnyMap scenario

```python
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` |