dove.core package

Contents

dove.core package#

dove.core#

Core module for DOVE optimization framework.

This module provides the foundational classes and functions for building and managing energy system models in DOVE. It includes classes for components, resources, cash flows, and transfer functions. These classes are essential for defining the structure and behavior of energy systems and for performing optimization and simulation tasks.

class dove.core.System[source]

Bases: object

The main class for creating and managing energy system models.

A System represents a collection of components and resources that form an energy system. It provides methods for adding components and resources, validating the system configuration, and solving optimization problems.

components

The components in the system.

Type:

list[Component]

resources

The resources in the system.

Type:

list[Resource]

time_index

The time periods for simulation.

Type:

list[int]

comp_map

A mapping of component names to component objects.

Type:

dict[str, Component]

res_map

A mapping of resource names to resource objects.

Type:

dict[str, Resource]

Parameters:
__init__(components=None, resources=None, time_index=None)[source]

Initialize a System instance.

Parameters:

  • components (list[Component] | None, optional) – The components to include in the system. If None, an empty list is used.

  • resources (list[Resource] | None, optional) – The resources to include in the system. If None, an empty list is used.

  • time_index (list[int] | None, optional) – The time periods for simulation. If None, [0] is used.

Return type:

None

add_component(comp)[source]

Add a component to the system.

Parameters:

comp (Component) – The component to add.

Returns:

The system instance for method chaining.

Return type:

Self

Raises:

ValueError – If the component validation fails (via verify method).

add_resource(res)[source]

Add a resource to the system.

Parameters:

res (Resource) – The resource to add.

Returns:

The system instance for method chaining.

Return type:

Self

build()[source]

Build the system model.

This method is intended to construct the necessary optimization problem based on the system configuration.

Raises:

NotImplementedError – This method is not yet implemented.

Return type:

None

property non_storage_comp_names: list[str]

The names of all non-storage components in the system.

solve(model_type='price_taker', **kw)[source]

Solve the system optimization problem.

Parameters:

  • model_type (str, default="price_taker") – The type of optimization model to use.

  • **kw (dict[str, Any]) – Additional keyword arguments to pass to the solver.

Returns:

The optimization results.

Return type:

Any

Raises:

ValueError – If the specified model_type is not registered.

property storage_comp_names: list[str]

The names of all storage components in the system.

summary()[source]

Print a summary of the system configuration.

Displays information about the number and names of components and resources, categorizes components into storage and non-storage types, and shows the time horizon length.

Return type:

None

verify_components_definition()[source]

Verify that components are valid.

Checks for: - Uniqueness of component names

Raises:

ValueError – If component names are not unique

Return type:

None

verify_resources_definition()[source]

Verify that resources are valid.

Checks for: - Type of resources - Uniqueness of resource names

Raises:

  • TypeError – If any resource is not of type Resource

  • ValueError – If resource names are not unique

Return type:

None

verify_time_series()[source]

Verify the integrity of the system’s time series.

Checks for: - Consistency of time series lengths with the system time index

Raises:

ValueError – If component capacity profile length doesn’t match time index length

Return type:

None

class dove.core.Component[source]

Bases: ABC

A base component class for energy system modeling.

This abstract class defines the common interface and validation for components in an energy system. Components have time-dependent capacity constraints, can consume and produce resources, and can have associated cashflows.

name

Unique identifier for the component.

Type:

str

max_capacity_profile

Time-dependent maximum operational capacity of the component.

Type:

TimeDependent

consumes

Resources consumed by this component.

Type:

list[Resource]

produces

Resources produced by this component.

Type:

list[Resource]

min_capacity_profile

Time-dependent minimum operational capacity; defaults to 0.0 for every timestep.

Type:

TimeDependent

capacity_resource

The resource that defines capacity, if any.

Type:

Resource | None

flexibility

Whether the component’s operation is flexible or fixed in optimization.

Type:

Literal[“flex”, “fixed”]

cashflows

Economic cashflows associated with this component.

Type:

list[CashFlow]

transfer_fn

Function defining resource conversion logic.

Type:

TransferFunc | None

Notes

This is an abstract base class that should be subclassed to implement specific component types like generators, grids, storage, etc.

Parameters:

  • name (str)

  • max_capacity_profile (TimeDependent)

  • consumes (list[Resource])

  • produces (list[Resource])

  • min_capacity_profile (TimeDependent)

  • capacity_resource (Resource | None)

  • flexibility (Literal[‘flex’, ‘fixed’])

  • cashflows (list[CashFlow])

  • transfer_fn (TransferFunc | None)

__init__(*, name, max_capacity_profile, consumes=<factory>, produces=<factory>, min_capacity_profile=<factory>, capacity_resource=None, flexibility='flex', cashflows=<factory>, transfer_fn=None)
Parameters:

  • name (str)

  • max_capacity_profile (TimeDependent)

  • consumes (list[Resource])

  • produces (list[Resource])

  • min_capacity_profile (TimeDependent)

  • capacity_resource (Resource | None)

  • flexibility (Literal[‘flex’, ‘fixed’])

  • cashflows (list[CashFlow])

  • transfer_fn (TransferFunc | None)

Return type:

None

capacity_resource: Resource | None = None
property consumes_by_name: list[str]

A list of resource names that are consumed by this component.

flexibility: Literal['flex', 'fixed'] = 'flex'
property produces_by_name: list[str]

A list of resource names that are produced by this component.

transfer_fn: TransferFunc | None = None
name: str
max_capacity_profile: TimeDependent
consumes: list[Resource]
produces: list[Resource]
min_capacity_profile: TimeDependent
cashflows: list[CashFlow]
class dove.core.Converter[source]

Bases: Component

A Component subclass that converts resources from one type to another.

The Converter class represents components that consume one set of resources and produce another, potentially different set of resources.

Parameters:

  • ramp_limit (float) – Maximum rate of change for the component’s capacity utilization between timesteps as a percent of capacity. Must be a value between 0 and 1. Default is 1.0 (no limit).

  • ramp_freq (int) – Frequency at which ramp limitations are applied. Default is 0 (every timestep).

  • **kwargs (Any) – Additional keyword arguments to pass to the parent Component class.

Notes

  • A Converter requires a ‘capacity_resource’ to determine its capacity limits.

  • If not specified, the capacity_resource will be automatically determined: - If the component consumes and produces the same resource, that resource is used. - Otherwise, capacity_resource must be explicitly specified.

  • When resources differ between input and output, a transfer_fn is required to define the conversion relationship.

Parameters:

  • name (str)

  • max_capacity_profile (TimeDependent)

  • consumes (list[Resource])

  • produces (list[Resource])

  • min_capacity_profile (TimeDependent)

  • capacity_resource (Resource | None)

  • flexibility (Literal[‘flex’, ‘fixed’])

  • cashflows (list[CashFlow])

  • transfer_fn (TransferFunc | None)

__init__(ramp_limit=1.0, ramp_freq=0, *, name, max_capacity_profile, consumes=<factory>, produces=<factory>, min_capacity_profile=<factory>, capacity_resource=None, flexibility='flex', cashflows=<factory>, transfer_fn=None)
Parameters:

  • ramp_limit (float)

  • ramp_freq (int)

  • name (str)

  • max_capacity_profile (TimeDependent)

  • consumes (list[Resource])

  • produces (list[Resource])

  • min_capacity_profile (TimeDependent)

  • capacity_resource (Resource | None)

  • flexibility (Literal[‘flex’, ‘fixed’])

  • cashflows (list[CashFlow])

  • transfer_fn (TransferFunc | None)

Return type:

None

ramp_freq: int = 0
ramp_limit: float = 1.0
name: str
max_capacity_profile: TimeDependent
consumes: list[Resource]
produces: list[Resource]
min_capacity_profile: TimeDependent
cashflows: list[CashFlow]
class dove.core.Sink[source]

Bases: Component

A component that consumes a resource and acts as an endpoint in the DOVE system.

A Sink is a specialized Component that only consumes resources without producing any. It represents destinations where resources exit the system, such as exporters, consumers, or terminal points in a resource flow network.

Parameters:

  • name (str) – The unique identifier for this sink component.

  • consumes (Resource) – The resource type this sink consumes.

  • **kwargs (Any) – Additional keyword arguments to pass to the Component parent class.

Raises:

ValueError – If ‘produces’ or ‘capacity_resource’ is found in the kwargs

Notes

By default a Sink creates a RatioTransfer function with a 1:1 ratio using the consumed resource as both input and mocked output.

__init__(name, consumes, **kwargs)[source]
Parameters:
Return type:

None

class dove.core.Source[source]

Bases: Component

A Source component that produces a specified resource in the DOVE simulation.

This component acts as a resource generator or provider in the system simulation, producing a specific resource type with a configurable capacity.

Parameters:

  • name (str) – The unique identifier for this source component.

  • produces (Resource) – The resource type that this source generates.

  • **kwargs (Any) – Additional arguments to pass to the parent Component class.

Raises:

ValueError – If ‘consumes’ or ‘capacity_resource’ is found in the kwargs

Notes

By default, a Source uses a RatioTransfer function with a 1:1 ratio, meaning it will output the same amount of resource as requested (up to its capacity limit).

__init__(name, produces, **kwargs)[source]
Parameters:
Return type:

None

class dove.core.Storage[source]

Bases: Component

Storage component for modeling energy storage systems.

This class represents a storage component in the energy system, capable of charging and discharging a specific resource.

resource

The resource type that this storage can store.

Type:

Resource

rte

Round-trip efficiency, between 0 and 1. Defaults to 1.0.

Type:

float

max_charge_rate

Maximum charge rate as a fraction of capacity per time period, between 0 and 1. Defaults to 1.0.

Type:

float

max_discharge_rate

Maximum discharge rate as a fraction of capacity per time period, between 0 and 1. Defaults to 1.0.

Type:

float

initial_stored

Initial stored amount as a fraction of capacity, between 0 and 1. Defaults to 0.0.

Type:

float

periodic_level

If True, storage level at the end of the simulation must equal the initial level. Defaults to True.

Type:

bool

\*\*kwargs

Additional keyword arguments to pass to the parent Component class. It’s important to note that some Component attributes may not be applicable to Storage components, such as produces, consumes, and capacity_resource. These attributes are set automatically based on the resource parameter as necessary.

Type:

Any

Notes

Storage components are treated differently from other components in terms of capacity and resource management. They can store energy for later use, and their operation is governed by the round-trip efficiency (rte) and charge/discharge rates.

Parameters:

  • resource (Resource)

  • rte (float)

  • max_charge_rate (float)

  • max_discharge_rate (float)

  • initial_stored (float)

  • periodic_level (bool)

  • name (str)

  • max_capacity_profile (TimeDependent)

  • consumes (list[Resource])

  • produces (list[Resource])

  • min_capacity_profile (TimeDependent)

  • capacity_resource (Resource | None)

  • flexibility (Literal[‘flex’, ‘fixed’])

  • cashflows (list[CashFlow])

  • transfer_fn (TransferFunc | None)

__init__(resource, rte=1.0, max_charge_rate=1.0, max_discharge_rate=1.0, initial_stored=0.0, periodic_level=True, *, name, max_capacity_profile, consumes=<factory>, produces=<factory>, min_capacity_profile=<factory>, capacity_resource=None, flexibility='flex', cashflows=<factory>, transfer_fn=None)
Parameters:

  • resource (Resource)

  • rte (float)

  • max_charge_rate (float)

  • max_discharge_rate (float)

  • initial_stored (float)

  • periodic_level (bool)

  • name (str)

  • max_capacity_profile (TimeDependent)

  • consumes (list[Resource])

  • produces (list[Resource])

  • min_capacity_profile (TimeDependent)

  • capacity_resource (Resource | None)

  • flexibility (Literal[‘flex’, ‘fixed’])

  • cashflows (list[CashFlow])

  • transfer_fn (TransferFunc | None)

Return type:

None

initial_stored: float = 0.0
max_charge_rate: float = 1.0
max_discharge_rate: float = 1.0
periodic_level: bool = True
rte: float = 1.0
resource: Resource
name: str
max_capacity_profile: TimeDependent
consumes: list[Resource]
produces: list[Resource]
min_capacity_profile: TimeDependent
cashflows: list[CashFlow]
class dove.core.CashFlow[source]

Bases: ABC

Abstract base class representing a financial cash flow.

This class serves as the foundation for different types of cash flows in the system. Cash flows have associated pricing profiles that can vary over time. If a price profile is not provided, it will default to using alpha as the fixed recurring value for the length of the simulation.

Parameters:

  • name (str) – Identifier for the cash flow.

  • price_profile (TimeDependent, optional) – Time-dependent pricing data, defaults to empty list.

  • alpha (float, optional) – Scaling factor for the cash flow magnitude, defaults to 1.0.

  • dprime (float, optional) – Adjustment factor for price calculations, defaults to 1.0.

  • scalex (float, optional) – Horizontal scaling factor for time-dependent functions, defaults to 1.0.

  • price_is_levelized (bool, optional) – Flag indicating if the price is levelized, defaults to False. (Not Implemented)

  • sign (int, optional) – Direction of the cash flow (positive or negative), defaults to 0.

__init__(name, price_profile=<factory>, alpha=1.0, dprime=1.0, scalex=1.0, price_is_levelized=False, sign=0)
Parameters:
Return type:

None

alpha: float = 1.0
dprime: float = 1.0
price_is_levelized: bool = False
scalex: float = 1.0
sign: int = 0
name: str
price_profile: list[float] | ndarray[tuple[int, ...], dtype[float64]]
class dove.core.Cost[source]

Bases: CashFlow

Represents a negative cash flow or cost.

This class is a subclass of the CashFlow abstract base class that specifically represents costs or expenses. A Cost instance always has a negative sign, which is enforced by setting the sign class attribute to -1.

sign

Fixed value of -1 to indicate that this cash flow represents a cost.

Type:

int

Examples

A recurring cost of $1,000.00 per time period:

>>> cost = Cost(name="Recurring Cost", alpha=1000.0)

Note that not specifying a price_profile will default to using alpha as the fixed value for the length of the simulation.

A time-dependent cost with a specific price profile:

>>> cost = Cost(
...     name="Time-Dependent Cost",
...     price_profile=[0.5, 1.0, 1.5],
...     alpha=1000.0)
Parameters:
__init__(name, price_profile=<factory>, alpha=1.0, dprime=1.0, scalex=1.0, price_is_levelized=False, sign=-1)
Parameters:
Return type:

None

sign: int = -1
name: str
price_profile: list[float] | ndarray[tuple[int, ...], dtype[float64]]
class dove.core.Resource[source]

Bases: object

A class representing a resource in the system.

This class is used to model resources that can be allocated, managed, or tracked within the system. Each resource has a name and an optional unit of measurement.

name

The unique name of the resource.

Type:

str

unit

The unit of measurement for the resource (e.g., “kg”, “liters”, “pieces”). Defaults to None if the resource doesn’t have a specific unit. (Currently not used)

Type:

str | None

Parameters:
__init__(name, unit=None)
Parameters:
Return type:

None

unit: str | None = None
name: str
class dove.core.Revenue[source]

Bases: CashFlow

A class representing revenue in a financial context.

Revenue is a subclass of CashFlow with a positive sign (+1), indicating incoming cash flow. It represents income generated from the sale of goods, services, or other business activities.

sign

The sign of the cash flow, set to +1 for revenue (incoming cash).

Type:

int

Parameters:
__init__(name, price_profile=<factory>, alpha=1.0, dprime=1.0, scalex=1.0, price_is_levelized=False, sign=1)
Parameters:
Return type:

None

sign: int = 1
name: str
price_profile: list[float] | ndarray[tuple[int, ...], dtype[float64]]
class dove.core.RatioTransfer[source]

Bases: object

A transfer class that enforces a ratio relationship between input and output resources.

This class models the conversion of one resource to another with a specified ratio. For example, it could represent energy conversion efficiency or material transformation.

Parameters:

  • input_res (Resource) – The input resource object.

  • output_res (Resource) – The output resource object.

  • ratio (float, default=1.0) – The conversion ratio from input to output. A ratio of 1.0 means the output equals the input. A ratio of 0.9 means 90% of input becomes output (10% loss). A ratio > 1.0 means the output is amplified relative to input.

Examples

Create a transfer that converts electricity to heat with 95% efficiency:

>>> transfer = RatioTransfer(
        input_res=Resource("electricity"),
        output_res=Resource("heat"),
        ratio=0.95
    )

Later, after component instantiation, the transfer can be used evaluate a constraint with dispatch activity values:

>>> transfer(inputs={"electricity": 100}, outputs={"heat": 95})
True
__init__(input_res, output_res, ratio=1.0)
Parameters:
Return type:

None

ratio: float = 1.0
input_res: Resource
output_res: Resource
class dove.core.PolynomialTransfer[source]

Bases: object

Represents a polynomial transfer function that maps input resources to output resources.

This class models a polynomial relationship between inputs and outputs, where the output is a sum of terms, each term being a coefficient multiplied by input resources raised to specified powers.

Parameters:

terms (list[tuple[float, dict[Resource, int]]]) – A list of terms in the polynomial. Each term is represented as a tuple containing: - A coefficient (float) - A dictionary (dict[Resource, int]) mapping Resource objects to their exponents in the term.

terms

A list of terms in the polynomial.

Type:

list[tuple[float, dict[Resource, int]]]

Examples

A combined cycle power plant model with efficiency curve: output = 0.35 * natural_gas^1 + 0.05 * natural_gas^0.5 would be represented as:

>>> PolynomialTransfer([
        (0.35, {natural_gas: 1}),
        (0.05, {natural_gas: 0.5})
    ])
__init__(terms)
Parameters:

terms (list[tuple[float, dict[Resource, int]]])

Return type:

None

terms: list[tuple[float, dict[Resource, int]]]

Submodules#

dove.core.cashflow module#

dove.core.cashflow#

Module containing cash flow classes for financial modeling in DOVE.

This module defines classes for representing financial cash flows in energy system models, including both costs and revenues. These cash flows can vary over time and have configurable scaling factors.

Classes#

CashFlow: Abstract base class for all cash flows Cost: Represents expenses or negative cash flows Revenue: Represents income or positive cash flows

class dove.core.cashflow.CashFlow[source]#

Bases: ABC

Abstract base class representing a financial cash flow.

This class serves as the foundation for different types of cash flows in the system. Cash flows have associated pricing profiles that can vary over time. If a price profile is not provided, it will default to using alpha as the fixed recurring value for the length of the simulation.

Parameters:

  • name (str) – Identifier for the cash flow.

  • price_profile (TimeDependent, optional) – Time-dependent pricing data, defaults to empty list.

  • alpha (float, optional) – Scaling factor for the cash flow magnitude, defaults to 1.0.

  • dprime (float, optional) – Adjustment factor for price calculations, defaults to 1.0.

  • scalex (float, optional) – Horizontal scaling factor for time-dependent functions, defaults to 1.0.

  • price_is_levelized (bool, optional) – Flag indicating if the price is levelized, defaults to False. (Not Implemented)

  • sign (int, optional) – Direction of the cash flow (positive or negative), defaults to 0.

name: str#
price_profile: list[float] | ndarray[tuple[int, ...], dtype[float64]]#
alpha: float = 1.0#
dprime: float = 1.0#
scalex: float = 1.0#
price_is_levelized: bool = False#
sign: int = 0#
__init__(name, price_profile=<factory>, alpha=1.0, dprime=1.0, scalex=1.0, price_is_levelized=False, sign=0)#
Parameters:
Return type:

None

class dove.core.cashflow.Cost[source]#

Bases: CashFlow

Represents a negative cash flow or cost.

This class is a subclass of the CashFlow abstract base class that specifically represents costs or expenses. A Cost instance always has a negative sign, which is enforced by setting the sign class attribute to -1.

sign#

Fixed value of -1 to indicate that this cash flow represents a cost.

Type:

int

Examples

A recurring cost of $1,000.00 per time period:

>>> cost = Cost(name="Recurring Cost", alpha=1000.0)

Note that not specifying a price_profile will default to using alpha as the fixed value for the length of the simulation.

A time-dependent cost with a specific price profile:

>>> cost = Cost(
...     name="Time-Dependent Cost",
...     price_profile=[0.5, 1.0, 1.5],
...     alpha=1000.0)
Parameters:
sign: int = -1#
__init__(name, price_profile=<factory>, alpha=1.0, dprime=1.0, scalex=1.0, price_is_levelized=False, sign=-1)#
Parameters:
Return type:

None

name: str#
price_profile: list[float] | ndarray[tuple[int, ...], dtype[float64]]#
class dove.core.cashflow.Revenue[source]#

Bases: CashFlow

A class representing revenue in a financial context.

Revenue is a subclass of CashFlow with a positive sign (+1), indicating incoming cash flow. It represents income generated from the sale of goods, services, or other business activities.

sign#

The sign of the cash flow, set to +1 for revenue (incoming cash).

Type:

int

Parameters:
sign: int = 1#
__init__(name, price_profile=<factory>, alpha=1.0, dprime=1.0, scalex=1.0, price_is_levelized=False, sign=1)#
Parameters:
Return type:

None

name: str#
price_profile: list[float] | ndarray[tuple[int, ...], dtype[float64]]#

dove.core.components module#

dove.core.components#

Module containing component classes that form the basis of DOVE models.

Components are connected through resources they consume and produce, forming a directed graph that represents a system model. Each component can have associated cash flows to motivate the optimization and transfer functions that define how resources flow through the component.

Classes#

  • Component: Abstract base class for all components in a DOVE model

  • Source: Component that produces a resource

  • Sink: Component that consumes a resource

  • Converter: Component that transforms input resources into output resources

  • Storage: Component that can store a resource for later use

Types#

  • TimeDependent: Type alias for time series data (list of floats or NumPy array)

class dove.core.components.Component[source]#

Bases: ABC

A base component class for energy system modeling.

This abstract class defines the common interface and validation for components in an energy system. Components have time-dependent capacity constraints, can consume and produce resources, and can have associated cashflows.

name#

Unique identifier for the component.

Type:

str

max_capacity_profile#

Time-dependent maximum operational capacity of the component.

Type:

TimeDependent

consumes#

Resources consumed by this component.

Type:

list[Resource]

produces#

Resources produced by this component.

Type:

list[Resource]

min_capacity_profile#

Time-dependent minimum operational capacity; defaults to 0.0 for every timestep.

Type:

TimeDependent

capacity_resource#

The resource that defines capacity, if any.

Type:

Resource | None

flexibility#

Whether the component’s operation is flexible or fixed in optimization.

Type:

Literal[“flex”, “fixed”]

cashflows#

Economic cashflows associated with this component.

Type:

list[CashFlow]

transfer_fn#

Function defining resource conversion logic.

Type:

TransferFunc | None

Notes

This is an abstract base class that should be subclassed to implement specific component types like generators, grids, storage, etc.

Parameters:

  • name (str)

  • max_capacity_profile (TimeDependent)

  • consumes (list[Resource])

  • produces (list[Resource])

  • min_capacity_profile (TimeDependent)

  • capacity_resource (Resource | None)

  • flexibility (Literal[‘flex’, ‘fixed’])

  • cashflows (list[CashFlow])

  • transfer_fn (TransferFunc | None)

name: str#
max_capacity_profile: TimeDependent#
consumes: list[Resource]#
produces: list[Resource]#
min_capacity_profile: TimeDependent#
capacity_resource: Resource | None = None#
flexibility: Literal['flex', 'fixed'] = 'flex'#
cashflows: list[CashFlow]#
transfer_fn: TransferFunc | None = None#
property produces_by_name: list[str]#

A list of resource names that are produced by this component.

property consumes_by_name: list[str]#

A list of resource names that are consumed by this component.

__init__(*, name, max_capacity_profile, consumes=<factory>, produces=<factory>, min_capacity_profile=<factory>, capacity_resource=None, flexibility='flex', cashflows=<factory>, transfer_fn=None)#
Parameters:

  • name (str)

  • max_capacity_profile (TimeDependent)

  • consumes (list[Resource])

  • produces (list[Resource])

  • min_capacity_profile (TimeDependent)

  • capacity_resource (Resource | None)

  • flexibility (Literal[‘flex’, ‘fixed’])

  • cashflows (list[CashFlow])

  • transfer_fn (TransferFunc | None)

Return type:

None

class dove.core.components.Source[source]#

Bases: Component

A Source component that produces a specified resource in the DOVE simulation.

This component acts as a resource generator or provider in the system simulation, producing a specific resource type with a configurable capacity.

Parameters:

  • name (str) – The unique identifier for this source component.

  • produces (Resource) – The resource type that this source generates.

  • **kwargs (Any) – Additional arguments to pass to the parent Component class.

Raises:

ValueError – If ‘consumes’ or ‘capacity_resource’ is found in the kwargs

Notes

By default, a Source uses a RatioTransfer function with a 1:1 ratio, meaning it will output the same amount of resource as requested (up to its capacity limit).

__init__(name, produces, **kwargs)[source]#
Parameters:
Return type:

None

class dove.core.components.Sink[source]#

Bases: Component

A component that consumes a resource and acts as an endpoint in the DOVE system.

A Sink is a specialized Component that only consumes resources without producing any. It represents destinations where resources exit the system, such as exporters, consumers, or terminal points in a resource flow network.

Parameters:

  • name (str) – The unique identifier for this sink component.

  • consumes (Resource) – The resource type this sink consumes.

  • **kwargs (Any) – Additional keyword arguments to pass to the Component parent class.

Raises:

ValueError – If ‘produces’ or ‘capacity_resource’ is found in the kwargs

Notes

By default a Sink creates a RatioTransfer function with a 1:1 ratio using the consumed resource as both input and mocked output.

__init__(name, consumes, **kwargs)[source]#
Parameters:
Return type:

None

class dove.core.components.Converter[source]#

Bases: Component

A Component subclass that converts resources from one type to another.

The Converter class represents components that consume one set of resources and produce another, potentially different set of resources.

Parameters:

  • ramp_limit (float) – Maximum rate of change for the component’s capacity utilization between timesteps as a percent of capacity. Must be a value between 0 and 1. Default is 1.0 (no limit).

  • ramp_freq (int) – Frequency at which ramp limitations are applied. Default is 0 (every timestep).

  • **kwargs (Any) – Additional keyword arguments to pass to the parent Component class.

Notes

  • A Converter requires a ‘capacity_resource’ to determine its capacity limits.

  • If not specified, the capacity_resource will be automatically determined: - If the component consumes and produces the same resource, that resource is used. - Otherwise, capacity_resource must be explicitly specified.

  • When resources differ between input and output, a transfer_fn is required to define the conversion relationship.

Parameters:

  • name (str)

  • max_capacity_profile (TimeDependent)

  • consumes (list[Resource])

  • produces (list[Resource])

  • min_capacity_profile (TimeDependent)

  • capacity_resource (Resource | None)

  • flexibility (Literal[‘flex’, ‘fixed’])

  • cashflows (list[CashFlow])

  • transfer_fn (TransferFunc | None)

ramp_limit: float = 1.0#
ramp_freq: int = 0#
__init__(ramp_limit=1.0, ramp_freq=0, *, name, max_capacity_profile, consumes=<factory>, produces=<factory>, min_capacity_profile=<factory>, capacity_resource=None, flexibility='flex', cashflows=<factory>, transfer_fn=None)#
Parameters:

  • ramp_limit (float)

  • ramp_freq (int)

  • name (str)

  • max_capacity_profile (TimeDependent)

  • consumes (list[Resource])

  • produces (list[Resource])

  • min_capacity_profile (TimeDependent)

  • capacity_resource (Resource | None)

  • flexibility (Literal[‘flex’, ‘fixed’])

  • cashflows (list[CashFlow])

  • transfer_fn (TransferFunc | None)

Return type:

None

name: str#
max_capacity_profile: TimeDependent#
consumes: list[Resource]#
produces: list[Resource]#
min_capacity_profile: TimeDependent#
cashflows: list[CashFlow]#
class dove.core.components.Storage[source]#

Bases: Component

Storage component for modeling energy storage systems.

This class represents a storage component in the energy system, capable of charging and discharging a specific resource.

resource#

The resource type that this storage can store.

Type:

Resource

rte#

Round-trip efficiency, between 0 and 1. Defaults to 1.0.

Type:

float

max_charge_rate#

Maximum charge rate as a fraction of capacity per time period, between 0 and 1. Defaults to 1.0.

Type:

float

max_discharge_rate#

Maximum discharge rate as a fraction of capacity per time period, between 0 and 1. Defaults to 1.0.

Type:

float

initial_stored#

Initial stored amount as a fraction of capacity, between 0 and 1. Defaults to 0.0.

Type:

float

periodic_level#

If True, storage level at the end of the simulation must equal the initial level. Defaults to True.

Type:

bool

\*\*kwargs

Additional keyword arguments to pass to the parent Component class. It’s important to note that some Component attributes may not be applicable to Storage components, such as produces, consumes, and capacity_resource. These attributes are set automatically based on the resource parameter as necessary.

Type:

Any

Notes

Storage components are treated differently from other components in terms of capacity and resource management. They can store energy for later use, and their operation is governed by the round-trip efficiency (rte) and charge/discharge rates.

Parameters:

  • resource (Resource)

  • rte (float)

  • max_charge_rate (float)

  • max_discharge_rate (float)

  • initial_stored (float)

  • periodic_level (bool)

  • name (str)

  • max_capacity_profile (TimeDependent)

  • consumes (list[Resource])

  • produces (list[Resource])

  • min_capacity_profile (TimeDependent)

  • capacity_resource (Resource | None)

  • flexibility (Literal[‘flex’, ‘fixed’])

  • cashflows (list[CashFlow])

  • transfer_fn (TransferFunc | None)

resource: Resource#
rte: float = 1.0#
max_charge_rate: float = 1.0#
max_discharge_rate: float = 1.0#
initial_stored: float = 0.0#
periodic_level: bool = True#
__init__(resource, rte=1.0, max_charge_rate=1.0, max_discharge_rate=1.0, initial_stored=0.0, periodic_level=True, *, name, max_capacity_profile, consumes=<factory>, produces=<factory>, min_capacity_profile=<factory>, capacity_resource=None, flexibility='flex', cashflows=<factory>, transfer_fn=None)#
Parameters:

  • resource (Resource)

  • rte (float)

  • max_charge_rate (float)

  • max_discharge_rate (float)

  • initial_stored (float)

  • periodic_level (bool)

  • name (str)

  • max_capacity_profile (TimeDependent)

  • consumes (list[Resource])

  • produces (list[Resource])

  • min_capacity_profile (TimeDependent)

  • capacity_resource (Resource | None)

  • flexibility (Literal[‘flex’, ‘fixed’])

  • cashflows (list[CashFlow])

  • transfer_fn (TransferFunc | None)

Return type:

None

name: str#
max_capacity_profile: TimeDependent#
consumes: list[Resource]#
produces: list[Resource]#
min_capacity_profile: TimeDependent#
cashflows: list[CashFlow]#

dove.core.resource module#

dove.core.resource#

This module provides the Resource class for representing and managing system resources. Resources are fundamental entities that can be allocated, tracked, and managed within the DOVE system. Each resource is identified by a unique name and can optionally have an associated unit of measurement.

Classes#

Resource: A dataclass representing a system resource with a name and optional unit.

Examples

``` # Create a resource for electricity with kilowatt-hours as unit electricity = Resource(name=”electricity”, unit=”kWh”)

# Create a resource without a specific unit labor = Resource(name=”labor”) ```

class dove.core.resource.Resource[source]#

Bases: object

A class representing a resource in the system.

This class is used to model resources that can be allocated, managed, or tracked within the system. Each resource has a name and an optional unit of measurement.

name#

The unique name of the resource.

Type:

str

unit#

The unit of measurement for the resource (e.g., “kg”, “liters”, “pieces”). Defaults to None if the resource doesn’t have a specific unit. (Currently not used)

Type:

str | None

Parameters:
name: str#
unit: str | None = None#
__init__(name, unit=None)#
Parameters:
Return type:

None

dove.core.system module#

dove.core.system#

Module containing the System class for modeling energy systems.

The System class forms the central component of DOVE models, connecting resources and components in a coherent framework for optimization and simulation. The System manages time series data, component interactions, and provides methods for building and solving optimization problems.

Classes#

  • System: Main class for creating and managing DOVE energy system models.

class dove.core.system.System[source]#

Bases: object

The main class for creating and managing energy system models.

A System represents a collection of components and resources that form an energy system. It provides methods for adding components and resources, validating the system configuration, and solving optimization problems.

components#

The components in the system.

Type:

list[Component]

resources#

The resources in the system.

Type:

list[Resource]

time_index#

The time periods for simulation.

Type:

list[int]

comp_map#

A mapping of component names to component objects.

Type:

dict[str, Component]

res_map#

A mapping of resource names to resource objects.

Type:

dict[str, Resource]

Parameters:
__init__(components=None, resources=None, time_index=None)[source]#

Initialize a System instance.

Parameters:

  • components (list[Component] | None, optional) – The components to include in the system. If None, an empty list is used.

  • resources (list[Resource] | None, optional) – The resources to include in the system. If None, an empty list is used.

  • time_index (list[int] | None, optional) – The time periods for simulation. If None, [0] is used.

Return type:

None

property non_storage_comp_names: list[str]#

The names of all non-storage components in the system.

property storage_comp_names: list[str]#

The names of all storage components in the system.

summary()[source]#

Print a summary of the system configuration.

Displays information about the number and names of components and resources, categorizes components into storage and non-storage types, and shows the time horizon length.

Return type:

None

verify_components_definition()[source]#

Verify that components are valid.

Checks for: - Uniqueness of component names

Raises:

ValueError – If component names are not unique

Return type:

None

verify_resources_definition()[source]#

Verify that resources are valid.

Checks for: - Type of resources - Uniqueness of resource names

Raises:

  • TypeError – If any resource is not of type Resource

  • ValueError – If resource names are not unique

Return type:

None

verify_time_series()[source]#

Verify the integrity of the system’s time series.

Checks for: - Consistency of time series lengths with the system time index

Raises:

ValueError – If component capacity profile length doesn’t match time index length

Return type:

None

add_component(comp)[source]#

Add a component to the system.

Parameters:

comp (Component) – The component to add.

Returns:

The system instance for method chaining.

Return type:

Self

Raises:

ValueError – If the component validation fails (via verify method).

add_resource(res)[source]#

Add a resource to the system.

Parameters:

res (Resource) – The resource to add.

Returns:

The system instance for method chaining.

Return type:

Self

build()[source]#

Build the system model.

This method is intended to construct the necessary optimization problem based on the system configuration.

Raises:

NotImplementedError – This method is not yet implemented.

Return type:

None

solve(model_type='price_taker', **kw)[source]#

Solve the system optimization problem.

Parameters:

  • model_type (str, default="price_taker") – The type of optimization model to use.

  • **kw (dict[str, Any]) – Additional keyword arguments to pass to the solver.

Returns:

The optimization results.

Return type:

Any

Raises:

ValueError – If the specified model_type is not registered.

dove.core.transfers module#

dove.core.transfers#

Core transfer functions for resource conversion in the DOVE optimization framework.

This module provides classes that model mathematical relationships between input and output resources in energy systems. These transfer functions represent physical or economic transformations such as energy conversion, efficiency losses, or material transformations.

The module defines two main transfer function types: - RatioTransfer: Simple linear relationship between inputs and outputs (e.g., efficiency) - PolynomialTransfer: More complex non-linear relationship described by polynomial terms

These transfer functions can be used to model various energy conversion processes including power plants, heat exchangers, fuel cells, and other technologies where inputs are transformed into outputs with specific characteristics.

class dove.core.transfers.RatioTransfer[source]#

Bases: object

A transfer class that enforces a ratio relationship between input and output resources.

This class models the conversion of one resource to another with a specified ratio. For example, it could represent energy conversion efficiency or material transformation.

Parameters:

  • input_res (Resource) – The input resource object.

  • output_res (Resource) – The output resource object.

  • ratio (float, default=1.0) – The conversion ratio from input to output. A ratio of 1.0 means the output equals the input. A ratio of 0.9 means 90% of input becomes output (10% loss). A ratio > 1.0 means the output is amplified relative to input.

Examples

Create a transfer that converts electricity to heat with 95% efficiency:

>>> transfer = RatioTransfer(
        input_res=Resource("electricity"),
        output_res=Resource("heat"),
        ratio=0.95
    )

Later, after component instantiation, the transfer can be used evaluate a constraint with dispatch activity values:

>>> transfer(inputs={"electricity": 100}, outputs={"heat": 95})
True
input_res: Resource#
output_res: Resource#
ratio: float = 1.0#
__init__(input_res, output_res, ratio=1.0)#
Parameters:
Return type:

None

class dove.core.transfers.PolynomialTransfer[source]#

Bases: object

Represents a polynomial transfer function that maps input resources to output resources.

This class models a polynomial relationship between inputs and outputs, where the output is a sum of terms, each term being a coefficient multiplied by input resources raised to specified powers.

Parameters:

terms (list[tuple[float, dict[Resource, int]]]) – A list of terms in the polynomial. Each term is represented as a tuple containing: - A coefficient (float) - A dictionary (dict[Resource, int]) mapping Resource objects to their exponents in the term.

terms#

A list of terms in the polynomial.

Type:

list[tuple[float, dict[Resource, int]]]

Examples

A combined cycle power plant model with efficiency curve: output = 0.35 * natural_gas^1 + 0.05 * natural_gas^0.5 would be represented as:

>>> PolynomialTransfer([
        (0.35, {natural_gas: 1}),
        (0.05, {natural_gas: 0.5})
    ])
terms: list[tuple[float, dict[Resource, int]]]#
__init__(terms)#
Parameters:

terms (list[tuple[float, dict[Resource, int]]])

Return type:

None

Contents