Api

pyconvexity.solvers.pypsa.api

High-level API for PyPSA solver integration.

Provides user-friendly functions for the most common workflows.

solve_network(db_path: str, scenario_id: Optional[int] = None, solver_name: str = 'highs', solver_options: Optional[Dict[str, Any]] = None, constraints_dsl: Optional[str] = None, discount_rate: Optional[float] = None, progress_callback: Optional[Callable[[int, str], None]] = None, return_detailed_results: bool = True, custom_solver_config: Optional[Dict[str, Any]] = None, include_unmet_loads: bool = True) -> Dict[str, Any]

Complete solve workflow: build PyPSA network from database, solve, store results (single network per database).

This is the main high-level function that most users should use. It handles the complete workflow of loading data from database, building a PyPSA network, solving it, and storing results back to the database.

Parameters:

Name	Type	Description	Default
db_path	str	Path to the database file	required
scenario_id	Optional[int]	Optional scenario ID (NULL for base network)	None
solver_name	str	Solver to use (default: "highs"). Use "custom" for custom_solver_config.	'highs'
solver_options	Optional[Dict[str, Any]]	Optional solver-specific options	None
constraints_dsl	Optional[str]	Optional DSL constraints to apply	None
discount_rate	Optional[float]	Optional discount rate for multi-period optimization	None
progress_callback	Optional[Callable[[int, str], None]]	Optional callback for progress updates (progress: int, message: str)	None
return_detailed_results	bool	If True, return comprehensive results; if False, return simple status	True
custom_solver_config	Optional[Dict[str, Any]]	Optional custom solver configuration when solver_name="custom" Format: {"solver": "actual_solver_name", "solver_options": {...}} Example: {"solver": "gurobi", "solver_options": {"Method": 2, "Crossover": 0}}	None
include_unmet_loads	bool	Whether to include unmet load components in the network (default: True)	True

Returns:

Type	Description
Dict[str, Any]	Dictionary with solve results - comprehensive if return_detailed_results=True, simple status otherwise

Raises:

Type	Description
DatabaseError	If database operations fail
ValidationError	If network data is invalid
ImportError	If PyPSA is not available

build_pypsa_network(db_path: str, scenario_id: Optional[int] = None, progress_callback: Optional[Callable[[int, str], None]] = None) -> pypsa.Network

Build PyPSA network object from database (single network per database).

This function loads all network data from the database and constructs a PyPSA Network object ready for solving or analysis. Useful when you want to inspect or modify the network before solving.

Parameters:

Name	Type	Description	Default
db_path	str	Path to the database file	required
scenario_id	Optional[int]	Optional scenario ID (NULL for base network)	None
progress_callback	Optional[Callable[[int, str], None]]	Optional callback for progress updates	None

Returns:

Type	Description
Network	PyPSA Network object ready for solving

Raises:

Type	Description
DatabaseError	If database operations fail
ValidationError	If network data is invalid
ImportError	If PyPSA is not available

solve_pypsa_network(network: pypsa.Network, db_path: str, scenario_id: Optional[int] = None, solver_name: str = 'highs', solver_options: Optional[Dict[str, Any]] = None, discount_rate: Optional[float] = None, store_results: bool = True, progress_callback: Optional[Callable[[int, str], None]] = None, custom_solver_config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]

Solve PyPSA network and optionally store results back to database (single network per database).

This function takes an existing PyPSA network (e.g., from build_pypsa_network), solves it, and optionally stores the results back to the database.

Parameters:

Name	Type	Description	Default
network	Network	PyPSA Network object to solve	required
db_path	str	Path to the database file (needed for result storage)	required
scenario_id	Optional[int]	Optional scenario ID (NULL for base network)	None
solver_name	str	Solver to use (default: "highs"). Use "custom" for custom_solver_config.	'highs'
solver_options	Optional[Dict[str, Any]]	Optional solver-specific options	None
discount_rate	Optional[float]	Optional discount rate for multi-period optimization (default: 0.0)	None
store_results	bool	Whether to store results back to database (default: True)	True
progress_callback	Optional[Callable[[int, str], None]]	Optional callback for progress updates	None
custom_solver_config	Optional[Dict[str, Any]]	Optional custom solver configuration when solver_name="custom" Format: {"solver": "actual_solver_name", "solver_options": {...}}	None

Returns:

Type	Description
Dict[str, Any]	Dictionary with solve results and statistics

Raises:

Type	Description
DatabaseError	If database operations fail (when store_results=True)
ImportError	If PyPSA is not available

load_network_components(db_path: str, scenario_id: Optional[int] = None) -> Dict[str, Any]

Load all network components and attributes as structured data (single network per database).

This low-level function loads network data without building a PyPSA network. Useful for analysis, validation, or building custom network representations.

Parameters:

Name	Type	Description	Default
db_path	str	Path to the database file	required
scenario_id	Optional[int]	Optional scenario ID (NULL for base network)	None

Returns:

Type	Description
Dict[str, Any]	Dictionary containing all network components and metadata

Raises:

Type	Description
DatabaseError	If database operations fail

apply_constraints(network: pypsa.Network, db_path: str, scenario_id: Optional[int] = None, constraints_dsl: Optional[str] = None) -> None

Apply custom constraints to PyPSA network (single network per database).

This function applies database-stored constraints and optional DSL constraints to an existing PyPSA network. Modifies the network in-place.

Parameters:

Name	Type	Description	Default
network	Network	PyPSA Network object to modify	required
db_path	str	Path to the database file	required
scenario_id	Optional[int]	Optional scenario ID (NULL for base network)	None
constraints_dsl	Optional[str]	Optional DSL constraints string	None

Raises:

Type	Description
DatabaseError	If database operations fail
ValidationError	If constraints are invalid

store_solve_results(network: pypsa.Network, db_path: str, scenario_id: Optional[int], solve_metadata: Dict[str, Any]) -> Dict[str, Any]

Store PyPSA solve results back to database (single network per database).

This low-level function stores solve results from a PyPSA network back to the database. Useful when you want full control over the solving process but still want to store results in the standard format.

Parameters:

Name	Type	Description	Default
network	Network	Solved PyPSA Network object	required
db_path	str	Path to the database file	required
scenario_id	Optional[int]	Scenario ID for result storage (NULL for base network)	required
solve_metadata	Dict[str, Any]	Dictionary with solve metadata (solver_name, solve_time, etc.)	required

Returns:

Type	Description
Dict[str, Any]	Dictionary with storage statistics

Raises:

Type	Description
DatabaseError	If database operations fail