simply package

Submodules

simply.actor module

class simply.actor.Actor(id, df, environment=None, battery=None, csv=None, ls=1, ps=1, pm={}, cluster=None, strategy: int = 0, pricing_strategy=None, assignedMarketMaker=None, assignedMarket=None, battery_cap=0, battery_initial_soc=0.5, ev_cap=0, ev_initial_soc=1.0, ev_available=0, ev_max_c_rate=1, ev_max_power=11, grid_connection_capacity=20)

Bases: object

Actor is the representation of a prosumer, i.e. is holding resources (load, photovoltaic/PV) and defining an energy management schedule, generating bids or asks and receiving trading results. The actor interacts with the market at every time step in a way defined by the actor strategy. The actor fulfills his schedule needs by trading energy. A successful energy trade can be guaranteed by placing orders with at least the market maker price, since the market maker is seen as unlimited supply. At the start of every time step the actor can place one order to buy or sell energy at the current time step. Basis for this order are a predicted schedule and a market maker price time series as input. After matching took place, the (monetary) bank and resulting soc is calculated taking into consideration the schedule and the acquired energy of this time step, i.e. bank and soc at the end of the time step. Afterward the time step is increased and a new prediction for the schedule and price is generated.

Parameters:

• id (int) – unique identifier of the actor

• df (pandas.DataFrame()) – DataFrame, column names “load”, “pv” and “price” are processed

• environment (.scenario.Environment()) – Environment reference for the actor

• battery (.battery.Battery()) – Battery used by the actor

• csv (str) – Filename in which this actor’s data should be stored

• ls (float) – (optional) Scaling factor for load time series

• ps (float) – (optional) Scaling factor for photovoltaic time series

• pm (dict) – (optional) Prediction multiplier used to manipulate prediction time series based on the data time series

• cluster (int) – cluster in which actor is located

• strategy (int) – Number for strategy [0-4]

• battery_cap (float) – Battery capacity used to create battery object. Only applied, if battery parameter is None (default: 0)

• battery_initial_soc (float) – Initial state of charge of newly created Battery object, Only applied, if battery parameter is None (default: 0.5)

• ev_cap (float) – Variable Battery capacity used to create VariableBattery object (default: 0)

• ev_initial_soc (float) – Initial state of charge of newly created variable battery object, (default: 0.5)

• ev_available (float) – initial availability status and if not strategy 4 override availability series and send a warning (default: 0)

• ev_max_c_rate (float) – maximum c-rate (default: 1)

• ev_max_power (float) – maximum ev charger power (default: 11)

• grid_connection_capacity (float) – maximum in/out flowing power at grid connection (default: 20)

Members:

idstr

Identifier of the actor to be set on creation

grid_idstr

[unused] Location of the actor in the network (init default: None)

tint

Actor’s current time slot should equal current market time slot (init default: 0)

horizonint

Horizon up to which energy management is considered (default defined in simply.config)

load_scalefloat

Scaling factor for load time series (default: init ls)

pv_scalefloat

Scaling factor for photovoltaic time series (default: init ps)

error_scalefloat

[unused] Noise scaling factor (default: 0)

batteryobject

Representation of a battery (default: None)

datapandas.DataFrame()

Actual generation and load time series as would be measured (default: init df)

predpandas.DataFrame()

Assumption of generation and load time series as would be predicted (default: init df + error)

csv_filestr

Filename in which this actor’s data should be stored

self.orderslist

List of generated orders

self.tradeddict

Dictionary of received trading results per time slot including matched energy and clearing prices

self.cluster: int

cluster in which actor is located

self.strategy: int

Number for strategy [0-3]

self.environment: .scenario.Environment()

environment reference for the actor

self.pricing_strategy: object

Strategy used to calculate prices for orders, which are planned in the future. Type can be function(steps,price,energy) or dict with keys (“name”, “params”). For further information check Pricing Strategies in ReadTheDocs or the documentation for get_price()

self.battery: .battery.Battery()

Battery used by the actor

self.bank: float

cumulated earnings and costs of this actor similar to a bank account balance

self.matched_energy_current_step: float

Amount of matched energy by orders of this actor in the current time step

self.predicted_soc: np.array()

predicted soc values for future time steps based on the battery state and planned actor behaviour

self.market_schedule: np.array()

planed energy amounts for interaction with the market_maker and basis of order generation

adjust_energy(energy, index=0)

Adjust energy amount by up to one energy unit to stay in soc boundaries

Parameters:

• energy (float) – energy amount for next order. Positive energy stands for buying of energy

• index (int) – number of time steps until a future order

Returns:

energy amount for order generation the current time step

Return type:

float

create_prediction()

Reset asset and schedule prediction horizon to the current planning time step self.t

property environment

generate_orders()

Generate new orders for current time slot according to predicted schedule and both store and return it.

Returns:

generated new orders

Return type:

list(Order)

get_default_market_schedule()

Return the default market schedule

The default market schedule is the schedule with flipped signs and minor adjustments to make use of residual energy in the battery. An energy need with negative sign in the schedule is met with buying energy in the market_schedule which has a positive sign

Returns:

default market schedule

get_environment()

get_limited_energy(energy, index)

Return the amount of energy that can be ordered at the current time step

Planned order generation can be moved forward if energy storage is possible. Energy storage can limit the amount of energy that can be bought/sold. This method returns the energy that can be procured at the current time step up to index. The limitation is calculated up to a future point in time. The index is the amount of simulation time steps up to this future point.

Parameters:

• energy (float) – energy amount of future order. Positive energy stands for buying of energy

• index (int) – number of time steps until a future order

Returns:

energy for order generation at the current time step

Return type:

float

get_market_schedule(strategy=None)

Generates a market_schedule for the actor which represents the strategy of the actor when to buy or sell energy. At the current time step the actor will always buy/ or sell this amount even at market maker price.

If strategy value is not specified, the actors attribute strategy is used and a warning is signaled. If the resulting strategy is not implemented or no flexibility exists, the strategy 0 is chosen that trades all energy instantly and a warning is signaled.

Parameters:

strategy (int) – Number representing the actor strategy from 0 to 3

Returns:

market_schedule with planed amounts of energy buying/selling per time step

get_mm_buy_prices()

get_mm_sell_prices()

get_price(steps, final_price, energy)

Return the price for order generation for a planned future order generation.

Planned order generation can be moved to an earlier time if energy storage is possible. Since urgency for energy procurement is lower, prices can be adjusted favorably for the actor. This method returns the current price based on the actor’s attribute pricing_strategy and a planned future order.

Parameters:

• steps (int) – number of time steps until a future order will be placed

• final_price (float) – price which would be used for a future order

• energy (float) – energy amount of future order. Positive energy stands for buying of energy , i.e. a lower price will be generated.

Returns:

price for order generation at the current time step

Return type:

float

get_steps_per_hour()

get_t_step()

property mm_buy_prices

property mm_sell_prices

plan_global_self_supply()

Returns market_schedule where energy needs are covered by the lowest price slots.

This strategy predicts the soc of the battery. If the soc would drop below 0 the market_schedule will cover the energy need by finding the cheapest time slot before or at the energy need time slot. :return: market_schedule

plan_global_trading()

Strategy to buy energy when profit is predicted by selling the energy later on when the flexibility is given

plan_selling_strategy()

Returns market_schedule where overcharges are sold at the highest possible price.

This strategy extends strategy 1. If the soc would rise over 1 the market_schedule will sell the energy by finding the most expensive time slot before or at the energy need time slot. Soc constrains will be considered, meaning that if needed, multiple time slots will be used to sell the energy. :return: market_schedule

plot(columns)

Plot columns from an actor’s asset data and prediction with suffix label.

Parameters:

columns (str) – name of the asset that should be plotted

predict_socs(clip=False, clip_value=1, planning_horizon=None)

Returns prediction of future socs based on schedule and market schedule

Creates a prediction for the planning horizon, which is not necessarily the horizon. The prediction is based on the soc of the battery, the schedule and the market schedule, which contains the amount the actor plans to buy or sell in a future time slot. Setting clip to true, does not allow values above the clipping value.

Parameters:

• planning_horizon – how far in the future should socs be predicted

• clip – should the values be clipped

• clip_value – value where socs are clipped to

Returns:

soc prediction for planning horizon

prepare_next_time_step()

Update actor and schedule and for next time step.

Should be executed after clearing. Changes actor attributes according to the events in the current time step The events can be the impact of schedule and trading on the battery soc or the bank / cost for the actor in this time step.

receive_market_results(time, sign, energy, price)

Callback function when order is matched. Updates the actor’s individual trading result.

Parameters:

• time (str) – time slot of market results

• sign (int) – for energy sold or bought represented by -1 or +1 respectively

• energy (float) – energy volume that was successfully traded

• price (float) – achieved clearing price for the stated energy

save_actor_result(dirpath=None)

Saves data and pred dataframes to given directory with actor specific csv file.

Parameters:

dirpath (str) – (optional) Path of the directory in which the actor csv file should be stored.

Returns:

pandas.DataFrame with additional historic data

save_actor_schedule(dirpath)

save_csv(dirpath)

Saves data and pred dataframes to given directory with actor specific csv file.

Parameters:

dirpath (str) – (optional) Path of the directory in which the actor csv file should be stored.

set_environment(environment)

set_var_battery(capacity, soc_initial, df, available=0, max_c_rate=4, refresh=True, min_soc=0.1)

Set a VariableBattery with a capacity and initial state of charge, availability to the local actor energy system, and a c-rate.

Changing availability only applicable for strategy 4, otherwise warning is printed.

Parameters:

• capacity – capacity of variable battery if available

• soc_initial – initial state of charge

• df – pd.DataFrame containing columns ‘ev_demand’ and ‘ev_avail’ for driving energy consumption and availability time series

• available – initial availability status and if not strategy 4 override availability series and send a warning (default 0)

• max_c_rate – c-rate of variable battery (default 4)

• refresh – update prediction (default True)

• min_soc – minimal soc attribute of battery, which is not automatically enforced

shift_market_schedule()

property steps_per_hour

strategy_with_optimisation()

Return the optimized market schedule

An energy need with negative sign in the schedule is met with buying energy in the market_schedule which has a positive sign

Returns:

optimized market schedule

property t_step

to_dict(external_data=False)

Builds dictionary for saving. external_data returns simple data instead of member dump.

Parameters:

external_data (dict) – (optional) Dictionary with additional data e.g. on prediction error time series

update_battery(_cache={})

Update the battery state with the current schedule and the matched energy in this step.

This function needs to be called once per time step to track the energy inside the battery. It takes the planned, i.e. predicted, schedule and changes the battery’s SOC accordingly.

Parameters:

_cache – cache of function calls, which SHOULD NOT be provided by user

class simply.actor.Order(type, time, actor_id, cluster, energy, price)

Bases: tuple

Struct to hold order

Parameters:

• type – sign of order, representing bid (-1) or ask (+1)

• time – timestamp when order was created

• actor_id – ID of ordering actor

• cluster – cluster of ordering actor

• energy – amount of energy the actor wants to trade. Will be rounded down(asks)/up(bids) according to the market’s energy unit

• price – bidding/asking price for one unit of energy

actor_id

Alias for field number 2

cluster

Alias for field number 3

energy

Alias for field number 4

price

Alias for field number 5

time

Alias for field number 1

type

Alias for field number 0

simply.actor.clip_soc(soc_prediction, upper_clipping=1, clipping_hull=None)

Clip the soc values above the upper_clipping threshold.

SOC predictions can be useful with and without soc restrictions. One restriction is that socs can not rise above a certain threshold, mostly 1. If this should be regarded, clipping of the socs is necessary. This is a more complex operation than just setting above 1 values to 1, since following values depend on the previous history, e.g. the socs history without clipping socs = [0.5, 1.0, 1.5, 1.8, 1.2, 1.3] in the clipped state is not [0.5, 1.0, 1.0, 1.0, 1.0, 1.0] but [0.5, 1.0, 1.0, 1.0, 0.4, 0.5]

Parameters:

• soc_prediction (np.array()) – soc_values which are clipped in place

• upper_clipping (float) – value above socs are clipped

simply.actor.create_from_csv(actor_id, asset_dict={}, start_date='2016-01-01', nb_ts=None, horizon=24, ts_hour=1, override_scaling=False, capacity=0)

Create actor instance with random asset time series and random scaling factors. Replace

Parameters:

• actor_id (str) – unique actor identifier

• asset_dict (Dict) – nested dictionary specifying ‘csv’ filename and column (‘col_index’) per asset or the time series index (‘index’) of the Actor

• start_date (str) – Start date “YYYY-MM-DD” of the DataFrameIndex for the generated actor’s asset time series

• nb_ts (int) – number of time slots that should be generated, derived from csv if None

• horizon – number of time slots to look into future to make the prediction for actor strategy

• ts_hour – number of time slots per hour, e.g. 4 results in 15min time slots

• override_scaling – if True the predefined scaling factors are overridden by the peak value of each csv file

Returns:

generated Actor object

Return type:

Actor

simply.actor.create_random(actor_id, start_date='2016-01-01', nb_ts=24, horizon=24, ts_hour=1)

Create actor instance with random asset time series and random scaling factors

Parameters:

• actor_id (str) – unique actor identifier

• start_date (str) – Start date “YYYY-MM-DD” of the DataFrameIndex for the generated actor’s asset time series

• nb_ts (int) – number of time slots that should be generated

• horizon – number of time slots to look into future to make the prediction for actor strategy

• ts_hour – number of time slots per hour, e.g. 4 results in 15min time slots

Returns:

generated Actor object

Return type:

Actor

simply.actor.get_geometric_price(steps, final_price, energy, param)

Return the price based on a geometric series

Geometric pricing changes the price according to the geometric series, e.g. with the factor 0.5 1, 1/2, 1/4, 1/8, 1/16 … and so on.

Parameters:

• steps (int) – number of steps until the future order has to be met

• final_price (float) – price for the future order (often equal to market maker price)

• energy (float) – amount of energy of the future order. Positive amounts mean buying energy

• param (list()) – geometric_factor and symmetric_bound_cap, with symmetric bound capping being optional

Returns:

simply.actor.get_harmonic_price(steps, final_price, energy, param)

Return the price based on a harmonic series

Harmonic pricing changes the price according to the harmonic series meaning 1, 1/2, 1/3, 1/4, 1/5 … and so on.

Parameters:

• steps (int) – number of steps until the future order has to be met

• final_price (float) – price for the future order (often equal to market maker price)

• energy (float) – amount of energy of the future order. Positive amounts mean buying energy

• param (list()) – half_life_steps and symmetric_bound_factor, with symmetric_bound_factor being optional

Returns:

simply.actor.get_linear_price(steps, final_price, energy, param)

Return the price based on a linear series

Parameters:

• steps (int) – number of steps until the future order has to be met

• final_price (float) – price for the future order (often equal to market maker price)

• energy (float) – amount of energy of the future order. Positive amounts mean buying energy

• param (list()) – gradient per time step, sign will be discarded

Returns:

simply.actor.get_price(pricing_strategy, steps, final_price, energy)

Returns the price at the current time step to generate an order early

Parameters:

• pricing_strategy (dict() or function) –

  strategy name and parameters or function with arguments steps, price and energy amount. Keys and values for the dictionary are dict(“name”:name,”param”: param) with allowed names [“linear”, “harmonic”, “geometric”]. For documentation of the param values can be found at their respective functions, e.g.:

  • get_linear_price()

  • get_harmonic_price()

  • get_geometric_price()

  or in ReadTheDocs.

• steps – amount of time step until interaction with market maker is planned

• final_price – price of the market maker interaction

• energy – amount of energy that is planned for trading. Positive amounts are buying and negative amounts are selling energy

Returns:

current price for order generation

Return type:

float

simply.config module

class simply.config.Config(cfg_file, project_dir=None)

Bases: object

Class holding all simulation-relevant information. Read in from configuration file.

After creation, the generated instance is available as Config.config, the parsed file as Config.parser. The attributes defining paths i.e. for loading/storing scenarios and results are only available, if project_path parameter is given e.g. using the match_market.py script.

Config attributes, grouped by section, with default in brackets below:

[default]

• start - initial timestep [8]

• nb_ts - number of timesteps to simulate [3]

• nb_actors - number of actors in network [5]

• nb_nodes - number of nodes in network [4]

• ts_per_hour - number of timesteps within one hour [4]

• list_ts - list of timesteps in simulation [generated, can’t be overridden]

• show_plots - show various plots [False]

• show_prints - show debug info in terminal [False]

• save_csv - save orders and matched results to csv files [True]

• scenario_path - path of scenario directory to load and/or store (optional)

• project_path - path of project directory for all in-/output files (optional)

• data_format - how to save actor data. Supported values

  csv: save data in separate csv file and all actors in one config file,

  [json]: save config and data per actor in a single file

• reset_market: if set, discard unmatched orders after each interval [True]

• update_scenario: if set, always save scenario in given path (even if loaded) [False]

• market_type: selects matching strategy. Supported values

  [pab]/basic (pay-as-bid)

  pac/2pac (two-sided pay-as-clear)

  fair (custom BEST market)

• energy_unit: size of energy units to be traded individually [0.01]

• weight_factor: conversion factor from grid fees to power network node weight [0.03]

• horizon: number of time steps to look ahead for prediction [24]

• actor_strategy: (currently unused) default actor strategy [None]

• schedule_update_step: every x-th time step the actor market schedule should be updated [1]

Parameters:

• cfg_file (str) – configuration file path with the attributes listed above.

• project_dir (str) – project folder path that should contain all in-/output files. [None]

• cfg_file – start

simply.market module

class simply.market.Market(network=None, grid_fee_matrix=None, time_step=None, name=None)

Bases: object

Representation of a market. Collects orders, implements a matching strategy for clearing, finalizes post-matching.

If a grid_fee_matrix parameter is not given, the default grid fee will be used.

This class provides a basic matching strategy which may be overridden.

accept_order(order, order_id=None, callback=None)

Handle new order.

Order must have same time step as market, type must be -1 or +1. Energy is quantized according to the market’s energy unit (round down). Signature of callback function: matching time, sign for energy direction (opposite of order type), matched energy, matching price.

Parameters:

• order – Order (type, time, actor_id, energy, price)

• callback – callback function (called when order is successfully matched)

• order_id – (optional) define order ID of the order to be inserted, otherwise consecutive numbers are used (if this leads to overriding indices, an IndexError is raised)

Returns:

add_grid_fee_info(matches)

Takes in a list of matches and returns the same list with an additional field ‘grid_fee’ added to each match dictionary.

Parameters:

matches – a list of dictionaries representing matches, with keys ‘bid_cluster’ and ‘ask_cluster’

Returns:

the input list of matches with the additional field ‘grid_fee’

append_to_csv(data, filename)

append_to_csv() appends the given data to the specified CSV file. Extends data by market_name.

Parameters:

• data – the data to be appended to the file, as a Pandas DataFrame

• filename – the name of the file to which data should be appended

Returns:

None

apply_grid_fee(ask, bid)

Updates the given ask price by adding the grid fee associated with the given bid and ask clusters.

Parameters:

• ask – the ask price to be updated

• bid – the bid used to determine the grid fee to be applied

Returns:

None

clear(reset=True)

Clear market. Match orders, call callbacks of matched orders, reset/tidy up dataframes.

Parameters:

reset – not retaining orders for next market cycle

Returns:

None

create_csv(filename, headers)

create_csv() creates a new CSV file with the given filename at the given path with the given headers.

Parameters:

• filename – the name of the file to be created

• headers – a list of strings representing the headers to be written to the file

Returns:

None

get_asks()

get_bids()

get_grid_fee(match=None, bid_cluster=None, ask_cluster=None)

Returns the grid fee associated with the bid and ask clusters of a given match.

Parameters:

• match – a dictionary representing a match, with keys ‘bid_cluster’ and ‘ask_cluster’

• bid_cluster – cluster id of ask

• ask_cluster – cluster id of bid

Returns:

the grid fee associated with the given bid and ask clusters

match(show=False)

Example matching algorithm: pay as bid, first come, first served.

Return structure: each match is a dict and has the following items:

time: current market time bid_id: ID of bid order ask_id: ID of ask order bid_actor: ID of bidding actor ask_actor: ID of asking actor bid_cluster: cluster of bidding actor ask_cluster: cluster of asking actor energy: matched energy (multiple of market’s energy unit) price: matching price

This is meant to be replaced in subclasses. :param show: show or print plots (mainly for debugging) :return: list of dictionaries with matches

print()

reset()

simply.market.filter_orders(asks, bids)

simply.market_2pac module

class simply.market_2pac.TwoSidedPayAsClear(name=None, network=None, grid_fee_matrix=None, time_step=None)

Bases: Market

Two sided Pay-As-Clear market mechanism, similar to https://gridsingularity.github.io/gsy-e/two-sided-pay-as-clear/

Each timestep, the highest bids are matched with the lowest offers.

get_grid_fee(match=None, ask_cluster=None, bid_cluster=None)

Returns the grid fee associated with the bid and ask clusters of a given match.

Parameters:

• match – a dictionary representing a match, with keys ‘bid_cluster’ and ‘ask_cluster’

• bid_cluster – cluster id of ask

• ask_cluster – cluster id of bid

Returns:

the grid fee associated with the given bid and ask clusters

match(show=False)

Example matching algorithm: pay as bid, first come, first served.

Return structure: each match is a dict and has the following items:

time: current market time bid_id: ID of bid order ask_id: ID of ask order bid_actor: ID of bidding actor ask_actor: ID of asking actor bid_cluster: cluster of bidding actor ask_cluster: cluster of asking actor energy: matched energy (multiple of market’s energy unit) price: matching price

This is meant to be replaced in subclasses. :param show: show or print plots (mainly for debugging) :return: list of dictionaries with matches

simply.market_2pac.plot_merit_order(bids, asks)

simply.market_fair module

class simply.market_fair.BestCluster(idx, bestmarket: BestMarket)

Bases: object

Class which keeps track of attributes resolving around a cluster and implements functionality to keep the best algorithm more readable.

A single BestCluster contains the bids of this cluster, the asks which are matched at the current state with these bids, a copy of unmatched asks, its own clearing price, and offers methods like getting possible profits if asks would be inserted

get_insertion_profit(ask) -> (<class 'float'>, <class 'dict'>)

Returns the profit for the ask if it were inserted, as well as the clearing dict

get_lowest_ask()

insert(ask, clearing)

masked_asks()

match_locally(**kwargs)

remove(**kwargs)

class simply.market_fair.BestMarket(name=None, network=None, grid_fee_matrix=None, time_step=None, disputed_matching='grid_fee')

Bases: Market

Custom fair market mechanism.

Similar to two-sided pay-as-clear, but searches globally for best matches, taking network fees into account.Nodes are first grouped into clusters (nodes with no transaction fees between them). Then, all clusters are evaluated individually, adding transaction fees to other clusters. If a match becomes disputed (order matched more than once), the higher offer is taken, while the other one is removed as a possible match and that cluster is re-evaluated. This converges to an optimal solution.

If a network and a grid_fee_matrix parameter are both supplied, Market will favour grid_fee_matrix.

clusters_to_match_exist(**kwargs)

find_best_profit_cluster(ask_id)

get_best_cluster(**kwargs)

get_bottom_asks(**kwargs)

get_clusters_to_match()

group_matches(**kwargs)

match(**kwargs)

Example matching algorithm: pay as bid, first come, first served.

Return structure: each match is a dict and has the following items:

time: current market time bid_id: ID of bid order ask_id: ID of ask order bid_actor: ID of bidding actor ask_actor: ID of asking actor bid_cluster: cluster of bidding actor ask_cluster: cluster of asking actor energy: matched energy (multiple of market’s energy unit) price: matching price

This is meant to be replaced in subclasses. :param show: show or print plots (mainly for debugging) :return: list of dictionaries with matches

match_new(**kwargs)

match_old(**kwargs)

remove_from_other_clusters(**kwargs)

resolve_dispute(**kwargs)

split_orders_to_energy_unit(**kwargs)

total_matched_energy_units()

simply.market_fair.get_clearing(*this_args, **kwargs)

simply.market_fair.time_it(function, timers={})

Decorator function to time the duration and number of function calls.

Parameters:

• function (function) – function do be decorated

• timers (dict) – storage for cumulated time and call number

Returns:

decorated function or timer if given function is None

Return type:

function or dict

simply.market_wrapper module

class simply.market_wrapper.BestClusterPayAsClearMatchingAlgorithm

Bases: MatchingAlgorithm

Wrapper class of the cluster-based market fair matching algorithm

classmethod get_matches_recommendations(mycoDict, grid_fee_matrix=None)

class simply.market_wrapper.BestPayAsBidMatchingAlgorithm

Bases: MatchingAlgorithm

Wrapper class for the pay as bid matching algorithm

classmethod get_matches_recommendations(mycoDict, grid_fee_matrix=None)

class simply.market_wrapper.BestPayAsClearMatchingAlgorithm

Bases: MatchingAlgorithm

Wrapper class for the pay as clear matching algorithm

classmethod get_matches_recommendations(mycoDict, grid_fee_matrix=None)

class simply.market_wrapper.MatchingAlgorithm

Bases: ABC

static get_market_matches(mycoDict, market, grid_fee_matrix=None)

Unpacks order dictionary per market and time slot and match the orders using the given market.

Parameters:

• mycoDict (dict) – hierarchical dictionary with market name and time slot each containing a dict with bids and offers in lists {‘bids’: [], ‘offers’: []}

• market – Market object that implements the matching algorithm

• grid_fee_matrix – two-dimensional nXn list used to calculate grid-fees e.g., [[0,1],[1,0]]

Returns:

list of dictionaries with matches in all given markets and time slots

abstract get_matches_recommendations(mycoDict)

simply.market_wrapper.accept_orders(market, time, orders)

simply.market_wrapper.generate_recommendations(market_id, time, bids, asks, matches)

simply.power_network module

class simply.power_network.PowerNetwork(name, network, weight_factor=None)

Bases: object

Representation of energy grid and associated grid fees.

add_actors_map(map)

add_actors_random(actors)

generate_grid_fee_matrix(weight_factor=1)

get_cluster_weights(c1, c2)

get_path_weight(u, v)

plot(show=True)

to_dict()

to_image(dirpath=PosixPath('.'))

to_json()

update_shortest_paths()

simply.power_network.create_power_network_from_config(network_path, weight_factor=1)

simply.power_network.create_random(nodes)

simply.power_network.create_random2(nodes)

simply.power_network.load_network()

simply.power_network.plot_topology_graphvis(G)

simply.power_network.remove_weights_from_leef_nodes(network)

simply.scenario module

class simply.scenario.Environment(steps_per_hour, add_actor_to_scenario, time_range=None, **kwargs)

Bases: object

Representation of the environment which is visible to all actors. Decouples scenario information from actors.

Parameters:

• buy_prices (iterable) – iterable of prices the market maker would buy energy for

• steps_per_hour (int) – amount of simulation steps per hour

• add_actor_to_scenario (function) – Function which adds the actor to py:attr:~simply.scenario.actors

• kwargs (dict) – kwargs for MarketMaker generation

Members:

time_stepint

current time_step of the environment

steps_per_hourint

amount of simulation steps per hour

add_actor_to_scenariofunction

Function which adds the actor to py:attr:~simply.scenario.actors

time_rangepd.DatetimeIndex / int

index that is used for all outputs and data indexing;

if it is not provided an int range is used based on the config

get_grid_feemethod

getter function of grid_fee of the Market

market_makerpy:class:~simply.market_maker.MarketMaker

market_maker in this environment (deprecated)

market_makerslist(py:class:~simply.market_maker.MarketMaker)

list of market_maker objects of this environment

class simply.scenario.Scenario(network, map_actors=None, buy_prices: array | None = None, rng_seed=None, steps_per_hour=None, time_range=None, **kwargs)

Bases: object

Representation of the world state: who is present (actors) and how everything is

connected (power_network). RNG (random number generator) seed is preserved so results can be reproduced.

add_market(market)

add_market_maker(buy_prices: Sized, **kwargs)

add_participant(participant, map_node=None, add_to_network=False)

add_participants(participants: Iterable, map_actors=None, add_to_network=False)

Add participants to the scenario.

If added to the network nodes, this is either done using the provided mapping dictionary or randomly.

Parameters:

• participants (simply.actor.Actor or simply.scenario.MarketMaker) – participants to be added

• map_actors – dictionary with actor_ids as key and node_id as value

• add_to_network (bool) – should the actors be added to the power network

Returns:

add_to_market_dict(market)

concat_actors_data()

Create a list of all actor data DataFrames and concatenate them using multi-column keys :return: DataFrame with multi-column-index (actor-level, asset-level)

create_strategies(**kwargs)

create_strategies_sequential(**kwargs)

from_config()

get_market()

property market

market_step(**kwargs)

next_time_step()

plot_participant_data()

Extracts asset data from all actors of the scenario and plots all time series per asset type as well as the aggregated sum per asset.

plot_prices(market_name='Market')

reset()

Reset the scenario after a simulation is run

save(dirpath, data_format)

Save scenario files to directory

dirpath: Path object

save_additional_results(dirpath)

set_market(market)

sync_market_time()

to_dict()

track_actor_schedule(dirpath, actor_id)

simply.scenario.create_random(num_nodes, num_actors, weight_factor, nb_ts=100, horizon=24)

simply.scenario.create_random2(num_nodes, num_actors, nb_ts=100, horizon=24)

simply.scenario.create_scenario_from_csv(dirpath, num_nodes, num_actors, weight_factor, ts_hour=4, nb_ts=None, horizon=24)

Load csv files from path and randomly select num_actors to be randomly

Parameters:

• dirpath – Path object

• num_nodes – number of nodes in the network

• num_actors – number of actors in the network

• weight_factor – weight factor used to derive grid fees

• ts_hour – number of time slot of equal length within one hour

• nb_ts – number of time slots to be generated

• horizon – number of time slots to look into future to make the prediction for actor strategy

simply.scenario.from_dict(scenario_dict)

simply.scenario.is_scenario_participant(obj)

simply.scenario.load(dirpath, data_format)

Create scenario from files that were generated by Scenario.save()

Parameters:

• dirpath – Path object

• data_format – File ending of actor data e.g. csv

simply.scenario.serialize_int64(obj)

simply.util module

simply.util.actor_print(actor, header=False, _header={})

Print several actor properties.

A header describing the properties as column names is printed the first call or when the argument “header” is set to True.

Parameters:

• actor (actor.Actor()) – Actor that is printed

• header (bool) – Should the header be printed

• _header (dict()) – do not use, private dictionary

simply.util.daily(df, daily_ts=24)

simply.util.dates_to_datetime(start_date='2016-01-01', nb_ts=1, horizon=24, ts_hour=1)

Converts string dates to datetime dtype and calculates end date from timesteps parameter.

simply.util.gaussian_pv(ts_hour, std)

simply.util.get_all_data(df, col='pv')

Select all columns ‘col’ at subcolumn level of the actors DataFrame.

Parameters:

• df – actor DataFrame with multi-column-index (actor_col, assets_col)

• col – selected assets_col

Returns:

DataFrame with single column level comprising all columns of equal sub-column name col

simply.util.round_price(price)

simply.util.round_prices_array(prices)

simply.util.run_obj_method(obj, method_name, *args, **kwargs)

simply.util.summerize_actor_trading(sc)

simply.util.timeit(func)

Module contents