Simulation Class¶
Simulations of prices, solar, and wind are often used in custom python scripts.
kyoslib_py
allows a direct access to the simulation set, produced by the KySim model. The choice of which KySim profile should be made available to aPrototype
model is made when defining aPrototype
profile. Please refer to the section describing Prototypes in the User manual of the KYOS Analytical platform.
Changelog¶
Version | Description |
---|---|
5.1.0 | Allow .get_spot() to get intraday and imbalance simulations |
5.0.7 | Specify keywords of pandas drop() method to remove warnings |
5.0.6 | Bugfix in volume simulations retrieval when identifier is an integer |
4.1.1 | Bugfix in error message when file does not exist |
4.1.0 | add half and quarter-hourly curves to get_fwd_curve method |
3.4.21 | Bugfix in load_sims_for_all_months() , when the optional input argument end_date is not provided. |
3.4.20 | Bugfix in get_fwd_product , when the commodity type is neither power nor gas, and the requested price is in the current month. |
3.4.18 | Bugfix in calculate_tradable_product() . Counting the delivery hours of the rolling products |
3.4.15 | Bugfix in calculate_tradable_product() which is a static method for get_fwd_product() |
3.4.5 | bugfix load predefined simulation files to speed up reading rolling products |
3.4.3 | bugfix convert daily peakload prices |
3.4.2 | bugfix correct the file name for non power commodities |
3.4.1 | bugfix in .convertfx() . |
3.4.0 | allow .get_spot() , .get_fwd_product() and .get_fwd_product_roll() to get simulations in all simulated currencies. |
3.3.1 | add base_currency_id to .get_fx() , so that more type of fx can be requested |
3.3.0 | add delivery_period_id to .get_fwd_product , so that the method makes more products such as a quarter product. |
3.2.0 | add .get_fwd_product_roll , so that simulations can be requested on a rolling basis. |
3.1.1 | bugfix only return commodities which are simulated. |
3.1.0 | add .get_fx() and .convert_fx() methods to the simulation class |
3.0.3 | correct self.end_date so that it takes into account the hours of the last simulation day. |
3.0.0 | Constructor doesn't read anymore from xml_node, use the from_xml or from_json methods to build to object |
2.2.2 | is_cent is added to get_spot and get_fwd_product |
2.0.3 | Running time of the get_spot is reduced |
1.6.9 | Replaced pymatreader with h5py |
1.6.8 | Replaced scipy and h5py with pymatreader |
1.5.14 | Added method get_weather_volume_sim(). |
1.0.0 | Simulation class added. |
Documentation¶
Simulation
¶
The Simulation class allows easy access to a particular KySim simulation job.
Attributes:
Name | Type | Description |
---|---|---|
n_sim |
int
|
Number of simulations |
trading_date |
datetime
|
Datetime object of the trading date on which the simulation job was based |
end_date |
datetime
|
Datetime object of the end date of the simulations |
commodities |
list
|
List of all the relevant Commodity objects associated with this simulation job |
model_currency |
Currency
|
the KySim model currency |
base_currency |
Currency
|
the base currency of the Kyos Platfom |
spot_folder |
str
|
Path to the folder containing the spot simulation outputs of the KySim job |
forward_folder |
str
|
Path to the folder containing the forward simulation outputs of the KySim job |
power_spot_granul |
int
|
Integer representing the granularity of spot simulations (daily only, hourly, half-hourly or quarter-hourly) |
Examples:
>>> from kyoslib_py.simulation import Simulation
>>> simulation_obj = Simulation.from_xml()
>>> simulation_obj.get_nr_simulations()
100
>>> simulation_obj.model_currency.get_name()
'GBP'
__init__(kysim_info, currency_set, commodity_set)
¶
Constructor of the Simulation class.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
kysim_info
|
dict
|
Dictionary with all the simulations properties expected keys:
|
required |
currency_set
|
CurrencySet
|
Available currencies. The set should contain at least all currencies related to the simulation profile. |
required |
commodity_set
|
CommoditySet
|
Available commodities. The set should contain at least all simulated commodities. |
required |
adjust_sims_is_cent(df_sims, request_is_cent, commodity)
¶
Adjusts the simulations from or to cents.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
df_sims
|
DataFrame
|
A dataframe with simulations. Note that all the columns should contain simulations |
required |
request_is_cent
|
bool
|
is the request to have the simulations in cent? |
required |
commodity
|
commodity
|
commodity object of the simulations. For this we can see if the simulations are in_cent or not. |
required |
Returns:
Type | Description |
---|---|
DataFrame
|
pd.DataFrame with if necessary converted simulations. |
calculate_tradable_product(commodity, start_delivery_mc, end_delivery_mc, month_codes, month_sims)
¶
This function calculates the tradable product. E.g. if product is quarter ahead we will have data in the following format (days, simulations, month_products). Month products will be 3 for a quarter.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
commodity
|
Commodity
|
an instance of the commodity object |
required |
start_delivery_mc
|
array
|
vector of month codes of the start delivery month |
required |
end_delivery_mc
|
array
|
vector of month codes of the end delivery month |
required |
month_codes
|
array
|
vector of month codes |
required |
month_sims
|
array
|
three-dimensional array with |
required |
Returns:
Type | Description |
---|---|
array
|
2d vector (days, simulations) of days on the rows and simulations in the columns. |
convert_fx(simulation_prices, from_currency_id, to_currency_id, delivery_period_name=None, delivery_period_id=None)
¶
Function which converts a set of simulations from one currency to another.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
simulation_prices
|
DataFrame
|
pd.DataFrame with simulated prices |
required |
delivery_period_name
|
str
|
granularity requested. hourly, daily and monthly supported. |
None
|
delivery_period_id
|
int
|
Kyos delivery period id. hourly, daily and monthly supported. For example: if the simulations are in hourly format you should prodivde 2, if daily you should provide 3. |
None
|
from_currency_id
|
int
|
ID number of the currency of simulations. |
required |
to_currency_id
|
int
|
ID number of the currency to which the currency should be converted. |
required |
Returns:
Type | Description |
---|---|
DataFrame
|
Dataframe containing the simulated prices, where each row represents a time period corresponding to the delivery_period supplied. |
Assumption
- All "values" are consecutive (no gaps in time steps).
- Currently, the method can convert only from/to the KySim model currency
Examples:
>>> from kyoslib_py.simulation import Simulation
>>> simulation_obj = Simulation()
>>> fwd_sims = simulation_set.get_fwd_product(
commodity_name='TTF',
fwd_year=2021,
fwd_month=5,
)
>>> simulation_set.convert_fx(
simulation_prices=fwd_sims,
delivery_period_name='monthly',
from_currency_id=1,
to_currency_id=2,
)
create_sim_i_colum()
¶
Returns:
Type | Description |
---|---|
array
|
with [sim_1,sim_2,...] |
from_xml(xml_path='./PrototypeSettings.xml', currency_set=None, commodity_set=None)
staticmethod
¶
This static method builds de simulation class object from a xml file.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
xml_path
|
str
|
Path to the xml file with KySimInfo. |
'./PrototypeSettings.xml'
|
currency_set
|
CurrencySet
|
Contains all relevant information relative to currencies and currency conversions. |
None
|
commodity_set
|
CommoditySet
|
Contains all relevant information relative to commodity settings. |
None
|
Returns:
Type | Description |
---|---|
Simulation
|
kyoslib_py.Simulation object |
get_commodity(requested_commodity_id=None, requested_commodity_name=None)
¶
Parameters:
Name | Type | Description | Default |
---|---|---|---|
requested_commodity_id
|
int
|
commodity id |
None
|
requested_commodity_name
|
str
|
commodity name |
None
|
Returns:
Type | Description |
---|---|
object
|
kyoslib_py.settings.Commodity |
get_currency(requested_currency_id=None, requested_currency_name=None)
¶
Parameters:
Name | Type | Description | Default |
---|---|---|---|
requested_currency_id
|
int
|
currency id of the requested currency. |
None
|
requested_currency_name
|
str
|
currency name of the requested currency. |
None
|
Returns:
Type | Description |
---|---|
Currency
|
kyoslib_py.settings.Currency object. |
get_delivery_type_name_from_id(delivery_type_id, group_name)
staticmethod
¶
Returns:
Name | Type | Description |
---|---|---|
delivery_type_name |
str
|
used in fwd products to find file name |
get_fwd_curve(commodity_name, delivery_period_name, start_date=None, end_date=None, del_type_id=1, dst=True)
¶
A Simulation class method to import forward curves used in the simulations.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
commodity_name
|
str
|
Name of the commodity for which the forward curve it to be imported, as matching that given in the XML settings file. |
required |
delivery_period_name
|
str
|
Curve granularity requested. half-hourly, hourly, daily and monthly supported. |
required |
start_date
|
datetime
|
Start date from which to begin the imported forward curve. |
None
|
end_date
|
datetime
|
Date at which the imported forward curve will end (inclusive of this date). |
None
|
del_type_id
|
int
|
ID number of the delivery type of the required forward curve as defined on the KYOS platform i.e. 1 = baseload, 2 = peakload, 3 = offpeak. Only available for monthly curves. |
1
|
dst
|
bool
|
Returns an hourly curve with Daylight Savings Time switches included (with missing hour and/or averaged double hour) if True, otherwise non-DST curve is outputted. Defaults to true; only meaningful with hourly (power) curves. |
True
|
Returns:
Type | Description |
---|---|
DataFrame
|
Dataframe containing the forward curve prices, where each row represents a new time period corresponding to the granularity supplied. |
Note
Forward curve are always imported in the currency of the commodity (which may be different from the model currency).
Examples:
>>> from kyoslib_py.simulation import Simulation
>>> simulation_obj = Simulation()
>>> hourly_fwd_curve = simulation_obj.get_fwd_curve(
commodity_name='UK Power',
delivery_period_name='hourly',
start_date=None,
end_date=None,
del_type_id=1,
dst=True,
)
>>> daily_fwd_curve = simulation_obj.get_fwd_curve(
commodity_name='TTF',
delivery_period_name='daily'
)
get_fwd_product(commodity_name, fwd_year, fwd_month, start_date=None, end_date=None, delivery_period_id=5, currency_name=None, currency_id=None, is_cent=None, delivery_type_id=1, carbon_floor=True)
¶
A Simulation class method to import forward prices simulations (monthly delivery only, daily granularity).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
commodity_name
|
str
|
Name of the commodity for which the forward simulations are to be imported, as matching the KYOS platform assigned name. |
required |
fwd_year
|
int
|
Year in which the simulated monthly forward contract delivers |
required |
fwd_month
|
int
|
Month in which the simulated monthly forward contract delivers |
required |
start_date
|
datetime
|
Start date from which to begin importing the forward product simulations. |
None
|
end_date
|
datetime
|
End date until which the simulated spot prices are to be imported. |
None
|
delivery_period_id
|
int
|
Kyos delivery period id matching the product, e.g. quarter = 6 |
5
|
currency_name
|
str
|
Name of the currency in which to import the simulations. Must be either the name of the model base currency or the commodity currency. Defaults to model base currency if not specified. |
None
|
currency_id
|
int
|
ID of the currency in which to import the simulations |
None
|
is_cent
|
bool
|
If true, the currency is quoted in cents. False otherwise. |
None
|
delivery_type_id
|
int
|
ID number of the delivery type of the required forward simulation as defined on the KYOS platform i.e. 1 = baseload, 2 = peakload, 3 = offpeak. |
1
|
carbon_floor
|
bool
|
Indicates whether the carbon floor adjusted spot simulations should be retrieved if the requested commodity belongs to the 'carbon' group. |
True
|
Returns:
Type | Description |
---|---|
DataFrame
|
Dataframe containing the individual simulations per column where each row represents a unique day. |
Examples:
>>> from kyoslib_py.simulation import Simulation
>>> simulation_obj = Simulation()
>>> monthly_forward_prices = simulation_obj.get_fwd_product(
commodity_name='TTF',
fwd_year=2020,
fwd_month=11,
start_date=dt.datetime(2020, 1, 1),
end_date=dt.datetime(2020, 10, 31),
currency_name='EUR',
del_type_id=1,
carbon_floor=False,
)
>>> monthly_forward_prices = simulation_obj.get_fwd_product(
commodity_name='TTF',
fwd_year=2020,
fwd_month=11,
)
get_fwd_product_roll(commodity_name, delivery_period_id, maturity, delivery_type_id=1, is_cent=None, currency_name=None, currency_id=None, start_date=None, end_date=None, carbon_floor=False)
¶
A Simulation class method to import forward rolling prices simulations.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
commodity_name
|
str
|
Name of the commodity for which the forward simulations are to be imported,vas matching the KYOS platform assigned name. |
required |
delivery_period_id
|
int
|
delivery period id matching the product, e.g. quarter = 6 |
required |
maturity
|
int
|
how many periods ahead is the product, e.g. two quarters ahead. |
required |
delivery_type_id
|
int
|
ID number of the delivery type of the required forward simulation as defined on the KYOS platform i.e. 1 = baseload, 2 = peakload, 3 = offpeak. |
1
|
is_cent
|
bool
|
true if you want the simulations in cent instead of whole currency unit |
None
|
currency_name
|
str
|
Name of the currency in which to import the simulations. Must be either the name of the model base currency or the commodity currency. Defaults to model base currency if not specified. |
None
|
currency_id
|
Id of the currency in which to import the simulations. Defaults to model base currency if not specified. |
None
|
|
start_date
|
datetime
|
Start date from which to begin importing the forward product simulations. |
None
|
end_date
|
datetime
|
latest simulated trading date. |
None
|
carbon_floor
|
bool
|
Indicates whether the carbon floor adjusted spot simulations should be retrieved if the requested commodity belongs to the 'carbon' group. Default is False. |
False
|
Returns:
Type | Description |
---|---|
DataFrame
|
Dataframe containing the individual simulations where each row represents a unique day. index : simulated trading days column 1: start delivery date column 2: end delivery date column 3->end: simulations |
get_fx(term_currency_id, base_currency_id=None, start_date=None, end_date=None)
¶
Get the daily FX simulated prices in a given period. The FX base currency is by default the KySim model currency, but can be adjusted via the base_currency_id argument.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
term_currency_id
|
int
|
The currency id to which you want to convert the prices. |
required |
base_currency_id
|
(optional, int)
|
id of the base currency. By default, this is the model currency id |
None
|
start_date
|
datetime
|
Start date from which to begin importing the fx simulations. |
None
|
end_date
|
datetime
|
End date until which the simulated fx prices are to be imported. |
None
|
Returns:
Type | Description |
---|---|
DataFrame
|
Dataframe containing the daily simulated prices, datetime as index and the fx per simulation in the columns. |
Examples:
>>> from kyoslib_py.simulation import Simulation
>>> simulation_obj = Simulation()
>>> fx_sims = simulation_set.get_fx(2)
get_load_currency_info(commodity, currency_id=None, currency_name=None)
¶
Determine in what currency simulations should be loaded based on a choice of currency_name or currency_id. This is necessary because KySim outputs simulations only in the model currency and in the commodity currency.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
commodity
|
commodity
|
the commodity for this the prices are simulated. |
required |
currency_name
|
str
|
Name of the currency in which to import the simulations. Must be in currency which is simulated. Defaults to model base currency. |
None
|
currency_id
|
int
|
currency of the currency in which to import the simulations. Must be in currency which is simulated. Defaults to model base currency. |
None
|
Returns:
Name | Type | Description |
---|---|---|
load_currency_name |
str
|
The name of the currency in which the simulations will be loaded. This relevant if the simulations are simulated in the commodity currency. If the request is not commodity currency the simulations are loaded in the model currency. Then, later this can be converted via the .convert_fx() method. |
load_currency_id |
int
|
the currency id in which the simulations should be loaded initially |
currency_id |
int
|
the currency id in which the simulation should be outputted finally |
get_spot(commodity_name, delivery_period_name='daily', delivery_period_id=None, start_date=None, end_date=None, currency_name=None, currency_id=None, is_cent=None, delivery_type_id=1, carbon_floor=True, price_type=None)
¶
A Simulation class method to import spot price simulations.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
commodity_name
|
str
|
Name of the commodity for which the spot simulations are to be imported, as matching the KYOS platform assigned name. |
required |
delivery_period_name
|
str
|
Granularity of the requested spot simulations. Defaults to daily simulations. |
'daily'
|
delivery_period_id
|
int
|
Kyos delivery period id matching the product, e.g. day = 3 and hour =2 |
None
|
start_date
|
datetime
|
Start date from which to import simulated spot prices. |
None
|
end_date
|
datetime
|
End date until which the simulated spot prices are to be imported. |
None
|
currency_name
|
str
|
Name of the currency in which to import the simulations. Must be in currency which is simulated. Defaults to model base currency. |
None
|
currency_id
|
int
|
currency of the currency in which to import the simulations. Must be in currency which is simulated. Defaults to model base currency. |
None
|
is_cent
|
bool
|
Are the simulations in cents. Defaults to false. |
None
|
delivery_type_id
|
int
|
ID number of the delivery type of the required spot simulation as defined on the KYOS platform i.e. 1 = baseload, 2 = peakload, 3 = offpeak. |
1
|
carbon_floor
|
bool
|
Indicates whether the carbon floor adjusted spot simulations should be retrieved if the requested commodity belongs to the 'carbon' group. Defaults to true. |
True
|
price_type
|
str
|
"hourlyspot", "fixed", "intraday", "imbalance-take", or "imbalance-feedin" |
None
|
Returns:
Type | Description |
---|---|
DataFrame
|
Dataframe containing the individual simulations per column where each row represents a unique time period e.g. day or hour. If the granularity is below daily, then the first column represents the average across the simulations. |
Examples:
>>> from kyoslib_py.simulation import Simulation
>>> simulation_obj = Simulation()
>>> simulation_spot_daily = simulation_obj.get_spot(
commodity_name='NBP',
delivery_period_name='daily',
start_date=dt.datetime(2020, 1, 1),
end_date=dt.datetime(2020, 1, 31),
currency_name='EUR',
del_type_id=1,
carbon_floor=False,
)
>>> simulation_spot_daily = simulation_obj.get_spot(commodity_name='TTF')
>>> implied_forward_curve = simulation_spot_daily.mean(axis =1)
get_weather_volume_sim(series_identifier, delivery_period_name, series_type, start_date=None, end_date=None)
¶
A Simulation class method to import weather/volume/renewable simulations.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
series_type
|
srting - choice between "weather" / "volume" / "renewable"
|
Type of the simulations. Volume and Weather simulations supported. Renewable is also a volume sim, it comes from recently introduced Renewable Asset object, which is a wrapper for holding more information related to Weather & Volume. |
required |
series_identifier
|
int | string
|
if series_type = "weather" => (int) the id of the historical weather time-series used by KySim if series_type = "volume" => (string) the user defined (in KySim) of the simulated volume simulations if series_type = "renewable" => (int) the user defined (in KySim) Renewable Asset id |
required |
delivery_period_name
|
str
|
Curve delivery_period requested. Hourly and Daily supported. |
required |
start_date
|
datetime
|
Start date from which to begin the imported weather/volume simulations. |
None
|
end_date
|
datetime
|
End date at which the imported weather/volume simulations will end (inclusive of this date). |
None
|
Returns:
Type | Description |
---|---|
DataFrame
|
(weather_volume_simulations). Size: (start_date:end_date, NumSim+1). Containing the individual simulations per column where each row represents a unique day/hour. The first column represents the average of the weather/volume simulations. |
Examples:
>>> from kyoslib_py.simulation import Simulation
>>> import datetime as dt
>>> simulation_obj = Simulation()
>>> start_date = dt.datetime(2020, 3, 24)
>>> end_date = dt.datetime(2020, 12, 31, 23)
>>> volume_simulations = simulation_obj.get_weather_volume_sim(
series_identifier="Dutch_Offshore",
elivery_period_name='Hourly',
series_type='Volume',
start_date=start_date,
end_date=end_date,
)
>>> end_date = dt.datetime(2020, 12, 31)
>>> weather_simulations = simulation_obj.get_weather_volume_sim(
series_identifier=25,
delivery_period_name='Daily',
series_type='Weather',
start_date=start_date,
end_date=end_date,
)
load_sims_for_all_months(month_codes, simulated_trading_dates, commodity_name, delivery_type_name, currency_name)
¶
This method creates a 3d np array of simulations, based on the product (start, end delivery), commodity and delivery type.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
month_codes
|
array
|
vector of relevant month codes, sorted from small to big |
required |
simulated_trading_dates
|
array
|
vector of trading days |
required |
commodity_name
|
str
|
name of the commodity |
required |
delivery_type_name
|
str
|
name of the delivery type |
required |
currency_name
|
str
|
currency name |
required |
Returns:
Name | Type | Description |
---|---|---|
month_sims |
array
|
(nr_simulated_days x nr_simulations x nr_months) |
SimulationError
¶
Bases: Exception
Capture errors which occurred using the kyoslib_py.simulation module.
Attributes:
Name | Type | Description |
---|---|---|
message |
str
|
explanation of the error |
Examples:
>>> raise SimulationError(message='Error reading currencies!')
>>>
>>> try:
simulation_spot_daily = simulation_obj.get_spot(comm_name='TTF')
except SimulationError as err:
print(err)
finally:
exit_code = 1
sys.exit(exit_code)
Helpers¶
kyoslib_py.simulation.from_xml