Component

Component

Component(name, proj)

Bases: Parameter_container

Base Class for all the components

A component has parameters (inherited from Parameter_container, with name, description and type) and variables (time series filled during the simulation). Components are created by the project (Project.new_component(), read_dict(), read_json()), not directly.

New component types inherit from this class: they add their parameters and variables in __init__(), validate them in check() and override the simulation methods (pre_simulation(), pre_iteration(), iteration(), post_iteration(), post_simulation()) that the project calls in this order. See the developer guide.

Create new component

Parameters:

Name Type Description Default
name str

name of the component

required
proj Project

project the component belongs to

required

project

project()

Project the component belongs to

Returns:

Type Description
Project

parent project

add_variable

add_variable(variable)

Add a new variable to the component

Parameters:

Name Type Description Default
variable Variable

variable to add, replaces any variable with the same key

required

del_variable

del_variable(variable)

Remove a variable from the component

Parameters:

Name Type Description Default
variable Variable

variable to remove

required

variable

variable(key)

Find and return a variable using its key

Parameters:

Name Type Description Default
key str

key of the variable, e.g. "temperature"

required

Returns:

Type Description
Variable

the variable (KeyError if it does not exist)

variable_dict

variable_dict()

Variables of the component

Returns:

Type Description
dict

{key: Variable}

variable_dataframe

variable_dataframe(units=False, frequency=None, value='mean', interval=None, pos_neg_columns=[])

Variables of the component as a table

Parameters:

Name Type Description Default
units bool

Includes unit in the name of the variable. Defaults to False.

False
frequency None or str

frequency of the values: None, "hourly", "daily", "monthly", "yearly". Defaults to None.

None
value str

"mean", "sum", "sum_pos", "sum_neg", "max" or "min". Defaults to "mean".

'mean'
interval None or list of two dates

List with the start and end dates of the period to be included in the dataframe, if the value is None all values are included.

None
pos_neg_columns list of str

List of variables that will be included in separate columns positive and negative values. Defaults to [].

[]

Returns:

Type Description
DataFrame

column "date" and one column per variable

get_all_referenced_components

get_all_referenced_components(_seen=None)

Get list of all referenced components, first itself. Look recursively at the referenced components

Parameters:

Name Type Description Default
_seen set

components already walked, used internally. References can form a cycle, if only because a wrong name gets typed into a reference, and without remembering where it has been the walk follows it until the stack runs out.

None

Returns:

Type Description
list of Component

referenced components and, last, the component itself

check

check()

Check if all is correct

Checks every parameter and creates the variables of the Parameter_variable and Parameter_variable_list parameters. Components that override it call this one first and add their own checks.

Returns:

Type Description
list of Message

errors found

get_parameter_variable_dictionary

get_parameter_variable_dictionary(time_index)

Values of the variables taken from Parameter_variable parameters at a time step

Used to evaluate Parameter_math_exp expressions.

Parameters:

Name Type Description Default
time_index int

index of the time step

required

Returns:

Type Description
dict

{symbol: value}

pre_simulation

pre_simulation(n_time_steps, delta_t)

Prepare the component before the time loop of the simulation

The base method sets up the variables of the Parameter_variable parameters and initialises every variable to zeros. Overriding methods call it first.

Parameters:

Name Type Description Default
n_time_steps int

number of time steps of the simulation

required
delta_t int

time step (s)

required

post_simulation

post_simulation()

Finish the component after the time loop of the simulation

pre_iteration

pre_iteration(time_index, date, daylight_saving)

Prepare the time step, before its iterations

The base method copies the values of the Parameter_variable parameters at the time step. Overriding methods call it first.

Parameters:

Name Type Description Default
time_index int

index of the time step

required
date datetime

date of the time step (center of the interval)

required
daylight_saving bool

daylight saving time is in effect

required

iteration

iteration(time_index, date, daylight_saving, n_iter)

Calculate one iteration of the time step

The project repeats the iterations of every component until all of them return True or the maximum number of iterations is reached.

Parameters:

Name Type Description Default
time_index int

index of the time step

required
date datetime

date of the time step (center of the interval)

required
daylight_saving bool

daylight saving time is in effect

required
n_iter int

number of the iteration in the time step, from 0

required

Returns:

Type Description
bool

the component has converged

post_iteration

post_iteration(time_index, date, daylight_saving, converged)

Finish the time step, after its iterations

Parameters:

Name Type Description Default
time_index int

index of the time step

required
date datetime

date of the time step (center of the interval)

required
daylight_saving bool

daylight saving time is in effect

required
converged bool

every component converged in the time step

required

variable_html

variable_html()

Key, description and unit of the variables as an HTML table

Returns:

Type Description
str

HTML table

function_html

function_html()

Short HTML help of the component's table methods

Returns:

Type Description
str

HTML text