API Reference

Contents

API Reference#

dove#

The Dispatch Optimization Variable Engine (DOVE) is a library used to configure energy system components and compute an optimized dispatch strategy for resources throughout the system.

class dove.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.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
class dove.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
class dove.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.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.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
class dove.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
class dove.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.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]]]
class dove.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

Subpackages#

Contents