# Sympheny Documentation

> Documentation for the Sympheny web application, REST API, Python SDK, and AI integrations.

## Home

- [Sympheny documentation](https://docs.sympheny.com/): Sympheny helps you design and optimize multi-energy systems. Work with it through any of these four surfaces.

## Web Application

- [Web Application](https://docs.sympheny.com/web-app/): Documentation for the Sympheny web application — from your first login to interpreting optimization results.
- [Getting started](https://docs.sympheny.com/web-app/getting-started/): Sympheny is a toolset for integrated energy system planning, suitable for scales ranging from buildings to cities. You can model energy systems with basic site details, quickly evaluate various…
- [Sign up and log in](https://docs.sympheny.com/web-app/getting-started/sign-up-and-login/): Upon signing up, you'll receive a confirmation email with a verification link. Click the link, set your password, and then log in to Sympheny.
- [Web app quick start](https://docs.sympheny.com/web-app/getting-started/quickstart/): In this example, you simulate a data center. The goal is to walk you through your first steps in the Sympheny web app, covering the mandatory features and some optional ones along the way. In the…
- [How-to guides](https://docs.sympheny.com/web-app/how-to/): The Sympheny web app organizes energy planning into a structured workflow. Projects are broken down into analyses, and each analysis is further divided into scenarios.
- [Managing projects](https://docs.sympheny.com/web-app/how-to/managing-projects/): This guide shows you how to create, edit, copy, share, delete, and manage your projects in Sympheny.
- [Managing analyses](https://docs.sympheny.com/web-app/how-to/managing-analyses/): The Analyses page is where you manage your analyses and their associated scenarios within a project.
- [Modeling scenarios](https://docs.sympheny.com/web-app/how-to/modeling-scenarios/): Modeling a scenario is a guided process. The scenario page walks you through a series of tabs, each dedicated to a specific element of your model, so you can build your scenario step by step:
- [General step](https://docs.sympheny.com/web-app/how-to/modeling-scenarios/general-step/): The currency shown in cost parameters and results. When you select a currency other than CHF, an exchange rate from CHF is applied to all economic data in the technology databases. All economic data…
- [Hubs step](https://docs.sympheny.com/web-app/how-to/modeling-scenarios/hubs-step/): In this step, you specify a list of the hubs that make up your site. Each hub must have a unique name, which identifies it in subsequent steps and in the results. For more information, see Hubs.
- [Energy carriers step](https://docs.sympheny.com/web-app/how-to/modeling-scenarios/energy-carriers-step/): This step lets you choose the types of energy your model considers. Each energy carrier needs a name, type, subtype, and color. For more information, see Energy carriers.
- [Energy demands step](https://docs.sympheny.com/web-app/how-to/modeling-scenarios/energy-demands-step/): In this step, you define all energy demands included in your scenario. Each demand must have a unique name and an energy carrier, and must be linked to at least one hub and one stage. For more…
- [On-site resources step](https://docs.sympheny.com/web-app/how-to/modeling-scenarios/on-site-resources-step/): Energy produced from on-site resources can be curtailed. Curtailment occurs when the available on-site resource leads to higher energy production than required by demand and export (see diagram…
- [Imports & exports step](https://docs.sympheny.com/web-app/how-to/modeling-scenarios/imports-exports-step/): In this step, you define the energy your scenario can purchase from outside the system (imports, such as grid electricity or natural gas) and the energy it can sell or send out (exports). For…
- [Conversion technology step](https://docs.sympheny.com/web-app/how-to/modeling-scenarios/conversion-technology-step/): There are two ways to add conversion technology candidates to your scenario: Add from Database and Create Custom. For more information, see Conversion technologies.
- [Storage technologies step](https://docs.sympheny.com/web-app/how-to/modeling-scenarios/storage-technologies-step/): In this step, you define the storage technology candidates the optimizer can install — systems that store an energy carrier for later use, such as batteries or thermal storage. For background, see…
- [Network links step](https://docs.sympheny.com/web-app/how-to/modeling-scenarios/network-links-step/): In this step, you define the network link candidates that let energy flow between the hubs of your scenario — for example, a district heating pipe or an electrical connection. For background, see the…
- [Executing scenarios](https://docs.sympheny.com/web-app/how-to/executing-scenarios/): Once a scenario is fully modeled, you execute it to run the optimization and produce results, which are covered in Scenario results.
- [Scenario results](https://docs.sympheny.com/web-app/how-to/scenario-results/): After executing a scenario, you can explore the optimization results in the results dashboard and download them as files. The meaning of each output value is described in Output parameters.
- [Database Center](https://docs.sympheny.com/web-app/how-to/database-center/): The Database Center gives you an overview of all your data. Saved data can be called from the scenario editor across all scenarios. Through the Database Center, you can also download databases or…
- [Upload databases](https://docs.sympheny.com/web-app/how-to/database-center/upload-databases/): While editing a scenario, you can upload single items to My User Database directly from the scenario editor (in Setup) by checking Save the technology for future use?.
- [Download databases](https://docs.sympheny.com/web-app/how-to/database-center/download-databases/): Downloading your database is useful when you want an overview of all your data, or need to do some post-processing or adjusting.
- [EnyTool](https://docs.sympheny.com/web-app/how-to/enytool/): Sympheny EnyTool is a software package that provides direct access to services and data from the Sympheny ecosystem. It connects with tools and datasets developed by:
- [RAMP tool suite](https://docs.sympheny.com/web-app/how-to/enytool/ramp-tool-suite/): The RAMP tool suite specializes in synthetic demand modelling for cases where measured datasets are unavailable or incomplete. It generates stochastic load profiles (domestic, hot water, EV, and…
- [Sympheny EnyFlow](https://docs.sympheny.com/web-app/how-to/enyflow/): Sympheny EnyFlow is a Jupyter Notebook environment that combines energy planning, advanced problem-solving, and visualization while directly leveraging the Sympheny web application and its API. You…
- [Optimization model](https://docs.sympheny.com/web-app/concepts/): Sympheny models an energy system as a network of hubs connected by energy flows. The optimizer decides which technologies to install, how to operate them, and how energy moves between hubs and over…
- [Stages](https://docs.sympheny.com/web-app/concepts/stages/): Technologies go through stages for installation, use, and potential reuse. Each stage has its own associated costs and demands. You define which stages each technology can be in. Technologies can be…
- [Hubs](https://docs.sympheny.com/web-app/concepts/hubs/): Sympheny lets you define different geographic areas or sites within your project as hubs. A hub can be an individual building or a group of buildings treated as a single unit. You specify the energy…
- [Energy carriers](https://docs.sympheny.com/web-app/concepts/energy-carriers/): An energy carrier is any substance or medium that contains energy and can be converted, stored, or delivered — a gaseous or solid fuel, an electric charge, thermal energy, solar irradiance, and so…
- [Energy demands](https://docs.sympheny.com/web-app/concepts/energy-demands/): Energy demands represent energy use. For example, a building uses heat for heating and hot water, electricity for appliances and mobility, and cold for cooling. An energy demand can also represent an…
- [Imports](https://docs.sympheny.com/web-app/concepts/imports/): Imports are energy purchased from outside the system, such as grid electricity or natural gas, at a price you define. Imports are configured together with exports in the Imports & exports step of the…
- [Exports](https://docs.sympheny.com/web-app/concepts/exports/): Exports are energy sold or sent outside the system — for example, feeding electricity back into the grid. Exports are configured together with imports in the Imports & exports step of the scenario…
- [On-site resources](https://docs.sympheny.com/web-app/concepts/on-site-resources/): On-site resources are renewable resources with intermittent (temporally varying) availability. In Sympheny, you can quickly generate solar irradiance profiles and wind profiles of 8,760 time steps…
- [Conversion technologies](https://docs.sympheny.com/web-app/concepts/conversion-technologies/): Conversion technologies are systems that transform one or more energy carriers into different types — for example, a gas boiler converting natural gas to heat. Each technology is defined by:
- [Storage technologies](https://docs.sympheny.com/web-app/concepts/storage-technologies/): Storage technologies are systems that store an energy carrier for later use — for example, batteries or thermal storage tanks. Like conversion technologies, each candidate is defined by technical,…
- [Technology packages](https://docs.sympheny.com/web-app/concepts/technology-packages/): Technology packages are bundles of technologies that the optimizer considers together. They build on the individual conversion and storage technology candidates defined in your scenario.
- [Network technologies](https://docs.sympheny.com/web-app/concepts/network-technologies/): Network technologies are connections that move energy between hubs — for example, a district heating pipe or an electrical link. Network link candidates are added in the Network links step of the…
- [Intra-hub networks](https://docs.sympheny.com/web-app/concepts/intra-hub-networks/): Intra-hub networks are connections that move energy within a single hub, in contrast to network technologies, which connect different hubs. Network link candidates are added in the Network links step…
- [Clustered profiles](https://docs.sympheny.com/web-app/concepts/clustered-profiles/): In the optimization process, machine-learning-generated clustered profiles are used to improve performance. These profiles are created by grouping similar daily patterns from all hourly input data in…
- [Sympheny demand profiles methodology](https://docs.sympheny.com/web-app/concepts/demand-profiles-methodology/): The demand profiles in Sympheny are based on different sources depending on the building use. They are stored in three levels, each contributing to the overall shape of the demand profile:
- [Glossary](https://docs.sympheny.com/web-app/concepts/glossary/): Short definitions of the terms used throughout the Sympheny optimization model. Each term links to its concept page — read those for the full explanation and parameters.
- [Discounted cash flow analysis](https://docs.sympheny.com/web-app/concepts/discounted-cash-flow-analysis/): Sympheny uses discounted cash flow (DCF) analysis to determine the present value of expected future cash flows. This approach is crucial for long-term energy projects, as it accounts for financing…
- [Capital recovery factor](https://docs.sympheny.com/web-app/concepts/capital-recovery-factor/): In Sympheny, the net present cost (NPC) is used to calculate the present value of all cash flows over a project's lifetime, taking into account the time value of money. NPC represents the discounted…
- [Parameters](https://docs.sympheny.com/web-app/concepts/parameters/): Reference definitions for every parameter used to build and read a Sympheny scenario.
- [Input parameters](https://docs.sympheny.com/web-app/concepts/parameters/input-parameters/): Sympheny lets you consolidate all your input data into a single Excel file. This file is organized into separate worksheets, with each worksheet representing a specific component of your scenario…
- [General parameters](https://docs.sympheny.com/web-app/concepts/parameters/general/)
- [Stages parameters](https://docs.sympheny.com/web-app/concepts/parameters/stages/)
- [Hubs parameters](https://docs.sympheny.com/web-app/concepts/parameters/hubs/)
- [Energy carriers parameters](https://docs.sympheny.com/web-app/concepts/parameters/energy-carriers/)
- [Conversion technology parameters](https://docs.sympheny.com/web-app/concepts/parameters/conversion-technologies/): Certain advanced parameters are not available to all plan users, but can be added through our add-on options. Contact our customer support team for a demo and to discuss how we could customize these…
- [Energy demands parameters](https://docs.sympheny.com/web-app/concepts/parameters/energy-demands/)
- [Output parameters](https://docs.sympheny.com/web-app/concepts/parameters/output-parameters/): Output parameters are the values Sympheny reports after an optimization run — the counterpart of the input parameters you configure when modeling. They appear in the results dashboard and in the…
- [What's new](https://docs.sympheny.com/web-app/whats-new/): Release notes for the Sympheny web application, newest first.
- [November 2025](https://docs.sympheny.com/web-app/whats-new/2025-november/): Sympheny deployed a set of upgrades that make it easier to prepare data, run focused optimizations, and communicate results — at building, site, and district scales.
- [April 2024](https://docs.sympheny.com/web-app/whats-new/2024-april/): We are thrilled to announce the release of the latest version of our web application! This release is packed with exciting features and improvements that will enhance your experience and empower you…
- [March 2023](https://docs.sympheny.com/web-app/whats-new/2023-march/): Update or replace all the different types of databases of your organization or your user at once with an Excel file. You can also download all the databases as an Excel file. Learn more
- [January 2023](https://docs.sympheny.com/web-app/whats-new/2023-january/): Upload an energy demand profile as an aggregation of several profiles and perform stochastic peak shaving on the demand profile. Learn more
- [November 2022](https://docs.sympheny.com/web-app/whats-new/2022-november/): Add Electric Vehicle (EV) Battery smart charging and discharging to your system optimization. These batteries are fixed storage units that can provide daily flexibility to your energy system.
- [September 2022](https://docs.sympheny.com/web-app/whats-new/2022-september/): Geolocate and organize all your projects at once on the same map. Order projects easily by name, favorite, or date created. A new sidebar gives access to the main sections of your project: Design,…
- [June 2022](https://docs.sympheny.com/web-app/whats-new/2022-june/): A new section in the user guide is added with detailed explanations of how to model specific Technology candidates, such as:
- [May 2022](https://docs.sympheny.com/web-app/whats-new/2022-may/): Watch: drawing Network Link candidates in the map
- [April 2022](https://docs.sympheny.com/web-app/whats-new/2022-april/): To protect your organization against lost or stolen credentials, you can request the use of MFA to log in to your Sympheny account.
- [March 2022](https://docs.sympheny.com/web-app/whats-new/2022-march/): Watch: GIS definition of your urban site
- [November 2021](https://docs.sympheny.com/web-app/whats-new/2021-november/): Save time by loading predefined sets of technologies into your project with one click. Create your own technology packages and save them for future use.
- [Troubleshooting and FAQs](https://docs.sympheny.com/web-app/troubleshooting/): If you run into a problem, start here.
- [FAQs](https://docs.sympheny.com/web-app/troubleshooting/faqs/): What does "optimization" exactly mean, and how is it applied in Sympheny? Our senior software development engineer, Youssef Sherif, answers a few questions that might have popped into your mind.
- [Common issues and solutions](https://docs.sympheny.com/web-app/troubleshooting/common-issues/): This page is in preparation. In the meantime, check the FAQs for answers to common questions, or contact support.
- [Contact support](https://docs.sympheny.com/web-app/troubleshooting/contact-support/): The fastest way to reach us is the Sympheny support portal — raise a request there for support questions, bug reports, and feedback.

## REST API

- [REST API](https://docs.sympheny.com/api/): The Sympheny REST API gives you programmatic access to everything you can do in the Sympheny web application: create projects and analyses, model energy hubs, demands, supply technologies and…
- [Authentication](https://docs.sympheny.com/api/authentication/): The API authenticates with JWT Bearer tokens. You exchange your Sympheny account credentials (the email and password you use to log in to the web application) for an access token, then send that…
- [Projects](https://docs.sympheny.com/api/reference/projects/): GET /sympheny-app/projects
- [Analyses](https://docs.sympheny.com/api/reference/analyses/): DELETE /sympheny-app/analysis/{analysisGuid}
- [Scenarios](https://docs.sympheny.com/api/reference/scenarios/): GET /sympheny-app/analysis/{guid}/scenario
- [Stages](https://docs.sympheny.com/api/reference/stages/): GET /sympheny-app/scenarios/stages/{guid}
- [Hubs](https://docs.sympheny.com/api/reference/hubs/): GET /sympheny-app/scenarios/hubs/{guid}
- [Energy carriers](https://docs.sympheny.com/api/reference/energy-carriers/): GET /sympheny-app/carriers/{carrierGuid}
- [Energy demands](https://docs.sympheny.com/api/reference/energy-demands/): DELETE /sympheny-app/scenarios/energy-demands/{guid}
- [Profiles](https://docs.sympheny.com/api/reference/profiles/): GET /sympheny-app/scenarios/{scenarioGuid}/profiles
- [Solar resources](https://docs.sympheny.com/api/reference/solar-resources/): DELETE /sympheny-app/scenarios/solar-on-site-resource/{guid}
- [Conversion technologies](https://docs.sympheny.com/api/reference/conversion-technologies/): GET /sympheny-app/v2/scenarios/conversion-technologies/{guid}
- [Storage technologies](https://docs.sympheny.com/api/reference/storage-technologies/): DELETE /sympheny-app/scenarios/storage-technologies/{guid}
- [Technology packages](https://docs.sympheny.com/api/reference/technology-packages/): DELETE /sympheny-app/scenarios/{scenarioGuid}/technology-packages/{guid}
- [Network technologies](https://docs.sympheny.com/api/reference/network-technologies/): DELETE /sympheny-app/scenarios/network-technologies/{guid}
- [Network links](https://docs.sympheny.com/api/reference/network-links/): DELETE /sympheny-app/scenarios/{scenarioGuid}/network-links/{network-link-guid}
- [Intra-hub network links](https://docs.sympheny.com/api/reference/intra-hub-network-links/): GET /sympheny-app/scenarios/intra-hub-network-links/{guid}
- [Imports and exports (impex)](https://docs.sympheny.com/api/reference/impex/): DELETE /sympheny-app/impex/{type}/{guid}
- [Auth](https://docs.sympheny.com/api/reference/auth/): External API - auth resource
- [Users](https://docs.sympheny.com/api/reference/users/): External API - users resource
- [Solver jobs](https://docs.sympheny.com/api/reference/solver-jobs/): POST /sense-api/ext/solver/jobs

## Python SDK

- [Python SDK](https://docs.sympheny.com/sdk/): sympheny-toolbox is the official Python client for the Sympheny API. It exposes every documented REST endpoint as a typed method, validates requests and responses with Pydantic models, and handles…
- [Workflows](https://docs.sympheny.com/sdk/workflows/): The SDK reference documents one method at a time. These guides string those methods together into the end-to-end flows you actually run: take a scenario from an Excel workbook, optimize it, and read…
- [Create a scenario from Excel](https://docs.sympheny.com/sdk/workflows/scenario-from-excel/): Turn a filled-in scenario Excel workbook into a Sympheny scenario you can execute. This is the fastest way to create a fully-specified scenario in one call instead of building it stage by stage.
- [Run a solver job](https://docs.sympheny.com/sdk/workflows/run-solver-job/): Submit a scenario to the Sympheny solver and wait for the optimization to finish. This mirrors clicking Execute in the web application, but scripted end to end.
- [Download the results](https://docs.sympheny.com/sdk/workflows/download-results/): Fetch the result file of a finished solver job, or link straight to its results dashboard in the web application.
- [Projects](https://docs.sympheny.com/sdk/reference/projects/): Operations on projects. Available on the client as client.projects.
- [Analyses](https://docs.sympheny.com/sdk/reference/analyses/): Operations on analyses. Available on the client as client.analyses.
- [Scenarios](https://docs.sympheny.com/sdk/reference/scenarios/): Operations on scenarios. Available on the client as client.scenarios.
- [Stages](https://docs.sympheny.com/sdk/reference/stages/): Operations on stages. Available on the client as client.stages.
- [Hubs](https://docs.sympheny.com/sdk/reference/hubs/): Operations on hubs. Available on the client as client.hubs.
- [Energy carriers](https://docs.sympheny.com/sdk/reference/energy_carriers/): Operations on energy carriers. Available on the client as client.energycarriers.
- [Energy demands](https://docs.sympheny.com/sdk/reference/energy_demands/): Operations on energy demands. Available on the client as client.energydemands.
- [Profiles](https://docs.sympheny.com/sdk/reference/profiles/): Operations on profiles. Available on the client as client.profiles.
- [Solar resources](https://docs.sympheny.com/sdk/reference/solar_resources/): Operations on solar on-site resources. Available on the client as client.solarresources.
- [Conversion technologies](https://docs.sympheny.com/sdk/reference/conversion_technologies/): Operations on conversion technologies. Available on the client as client.conversiontechnologies.
- [Storage technologies](https://docs.sympheny.com/sdk/reference/storage_technologies/): Operations on storage technologies. Available on the client as client.storagetechnologies.
- [Technology packages](https://docs.sympheny.com/sdk/reference/technology_packages/): Operations on technology packages. Available on the client as client.technologypackages.
- [Network technologies](https://docs.sympheny.com/sdk/reference/network_technologies/): Operations on network technologies. Available on the client as client.networktechnologies.
- [Network links](https://docs.sympheny.com/sdk/reference/network_links/): Operations on network links. Available on the client as client.networklinks.
- [Intra-hub network links](https://docs.sympheny.com/sdk/reference/intra_hub_network_links/): Operations on intra-hub network links. Available on the client as client.intrahubnetworklinks.
- [Imports and exports (impex)](https://docs.sympheny.com/sdk/reference/impex/): Operations on energy imports and exports. Available on the client as client.impex.
- [Solver jobs](https://docs.sympheny.com/sdk/reference/solver_jobs/): Operations on solver jobs. Available on the client as client.solverjobs.
- [Users](https://docs.sympheny.com/sdk/reference/users/): User account endpoints. Available on the client as client.users.
- [Unofficial endpoints](https://docs.sympheny.com/sdk/reference/unofficial/): Endpoints outside the official documented Sympheny API. May change without notice. Available on the client as client.unofficial.
- [Shared models](https://docs.sympheny.com/sdk/reference/models/common/): Models used across several resource groups.
- [Project and analysis models](https://docs.sympheny.com/sdk/reference/models/projects/)
- [Scenario, stage, and hub models](https://docs.sympheny.com/sdk/reference/models/scenarios/)
- [Energy models](https://docs.sympheny.com/sdk/reference/models/energy/)
- [Technology and network models](https://docs.sympheny.com/sdk/reference/models/technologies/)
- [Solver job and user models](https://docs.sympheny.com/sdk/reference/models/solver/): Root model wrapping AnyUrl.

## Use with AI

- [Use with AI](https://docs.sympheny.com/ai/): Sympheny is built to be driven by AI assistants and coding agents. This section covers the ways to connect Sympheny to an AI tool.
- [MCP server setup](https://docs.sympheny.com/ai/mcp/): The Sympheny MCP server exposes the Sympheny API to AI assistants over the Model Context Protocol, so a model can create scenarios, run solver jobs, and read results without you wiring up HTTP calls…