Skip to content

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 a Prototype model is made when defining a Prototype 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:

  • SpotSimFolder (str): Path to the folder containing the spot simulation outputs of the KySim job

  • FwdSimFolder (str): Path to the folder containing the forward simulation outputs of the KySim job

  • OtherSimFolder (str): Path to the folder containing the other simulation outputs of the KySim job

  • TradingDate (datetime): Datetime object of the trading date on which the simulation job was based

  • PowerSpotGranularity (int): Integer representing the granularity of spot simulations (daily only, hourly, half-hourly or quarter-hourly)

  • EndDate (datetime): Datetime object of the end date of the simulations

  • NrSimulations( int): Number of simulations

  • ModelCurrency (kyoslib_py.settings.Currency): The KySim model currency

  • BaseCurrency (kyoslib_py.settings.Currency): The base currency of the Kyos Platform

  • curve_info (dict): With commodity_id, fwd_curve_id, spot_source_id per simulated commodity

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