parameters

Classes used to represent the attributes of the building that can be varied, such as the thickness of the insulation, or the window to wall ratio. These parameters are separate from the value that they take on during any evaluation of the model.

class parameters.AbstractFieldSelector(field_name)

Base class for selectors that modify one field in one or more objects in an EnergyPlus building

add(building, value) → None

Adds to this field in the building by the provided value

Parameters:

• building – the building to modify
• value – the value to add to this field

Returns:

get(building) → List[T]

Gets the current values of this field from a building

Parameters:building – the building to retrieve values from Returns:a list containing the current values of this selector’s fields

get_objects(building) → List[T]

Returns a list of the object this selector applies to

Parameters:building – the building to search for objects Returns:a list of the objects this selector applies to

multiply(building, value) → None

Multiplies this field in the building by the provided value

Parameters:

• building – the building to modify
• value – the value to multiply this field by

Returns:

set(building, value) → None

Sets this field in the building to the provided value

Parameters:

• building – the building to modify
• value – the value to set this field to

Returns:

class parameters.CategoryDescriptor(options: Iterable[T_co], **kwargs)

Represents a value that is selected from a list of possible options.

Parameters:options – a list of possible value this parameter can be set to

sample(value)

Takes a value in the range 0-1 and returns a valid value for this parameter

validate(value)

Checks if value is a valid value for this Descriptor.

Parameters:value – The value to check. Returns:True if the value is valid False otherwise

class parameters.CategoryParameter(options: Iterable[T_co], **kwargs)

Represents a value that is selected from a list of possible options.

Warning

CategoryParameter is actually a kind of Descriptor, not a Parameter. This naming may be confusing.

Deprecated since version 2.2.0: CategoryParameter has been renamed CategoryDescriptor. Use CategoryDescriptor in the future instead.

Parameters:options – a list of possible value this parameter can be set to

class parameters.FieldSelector(class_name: str = None, object_name: str = None, field_name: str = None)

A selector that modifies one or more fields in an EnergyPlus building, based on the class, object and field names

Parameters:

• class_name – class of the object to modify ex: ‘Material’
• object_name – name of the object to modify ex: ‘Mass NonRes Wall Insulation’
• field_name – name of the field to modify ex: Thickness

get_objects(building) → List[T]

Retrieves the objects that this selector will affect from the building.

Parameters:building – the building to search Returns:a list of the objects found

class parameters.FilterSelector(get_objects, field_name)

A selector that uses a custom function to find which objects it should modify

Parameters:

• get_objects – a function that takes a building and returns the objects this selector should modify
• field_name – the field to modify

get_objects(building)

Returns a list of the object this selector applies to

Parameters:building – the building to search for objects Returns:a list of the objects this selector applies to

class parameters.GenericSelector(set: Callable = None, get: Callable = None, setup: Callable = None)

A selector that supports custom get/set functions

Parameters:

• set – The function to use when setting. Must accept a building and a value. Can modify the building in any way.
• get – The function to use when getting a value from a building. Must accept a building, and should return a list of the current values of the fields this selector affects.
• setup – The function to use when setting up the building. This function must accept a building. It may modify the building in any way. This will be run once when the evaluator is initialized with a building. (or when the building the evaluator uses is changed.)

get(building)

A custom function for getting the current values of this field from a building

Parameters:building – the building to retrieve values from

set(building, *values)

Redirects to the custom function given. The building and values are passed to the function.

Parameters:

• building – the building to modify
• values – the values to use when modifying the building

setup(building)

A custom function for modifying the building so that it is ready for this selector

Parameters:building – the building to modify

class parameters.Parameter(selector: besos.IO_Objects.Selector = None, value_descriptors: Union[besos.IO_Objects.Descriptor, List[besos.IO_Objects.Descriptor]] = None, name='', *, value_descriptor: besos.IO_Objects.Descriptor = None)

Parameters:

• selector – a Selector describing how to modify the building
• value_descriptors – a Descriptor specifying which values to use
• name – the name of the Parameter. Used for readability and column labelling.

name

Deprecated since version 2.0.0.

Parameters are no longer nameable. Use the name(s) of this Parameter’s Descriptor(s) instead

platypus_type

The platypus equivalent of this parameter

Deprecated since version 2.0.0: Does not support multiple Descriptors per Parameter.Use the platypus_type of this Parameter’s Descriptor(s) instead.

sample(value: float)

Takes a value in the range 0-1 and returns a valid value for this parameter

Deprecated since version 2.0.0: Does not support multiple descriptors per parameter.Use the sample method of the this Parameter’s Descriptor(s) instead.

transformation_function(building, value_dict) → None

Mutates the building based on the value provided.

validate(value)

Checks if value is a valid value for this parameter.

param value: return:True if the value is valid False otherwise

Deprecated since version 2.0.0: Does not support multiple Descriptors per Parameter.Use the validate method of this Parameter’s Descriptor(s) instead.

value_descriptor

Deprecated since version 2.0.0.

Does not support multiple Descriptors per Parameter.Use the value_descriptors of this Parameter instead.

class parameters.ParameterEH

A parameter for use with EnergyHub

Deprecated since version 2.0.0: Use a PathSelector and a Parameter instead. These have been swapped in automatically.

class parameters.PathSelector(parameter_path=None)

A Selector for modifying EnergyHub objects using a path.

Parameters:parameter_path – the path to the parameter to modify for the EnergyHub

get(hub)

Get the current value of this attribute of the building

Parameters:building – Returns:

set(hub, value)

Modifies building, setting the attribute this selector corresponds to to value

Parameters:

• building – the building to modify.
• value – the value to set this selector’s attribute to.

Returns:

setup(hub) → None

Modifies the building so that it is ready for this selector

class parameters.RangeDescriptor(min_val: float = 0, max_val: float = inf, name='')

Represents an value that is selected from an interval.

Parameters:

• max_val – the minimum value
• min_val – the maximum value

pandas_type

alias of builtins.float

sample(value: float) → float

Transforms a value in [0, 1] into a value in [min, max]. This transformation is uniform.

Parameters:value – a value in the interval [0, 1] Returns:a value from the interval [min, max]

validate(value: float) → bool

Checks if value is contained within the range described by this Descriptor

Parameters:value – The value to check. Returns:True if the value in the range, False otherwise.

class parameters.RangeParameter(min_val: float = 0, max_val: float = inf, name='')

Represents an value that is selected from an interval.

Warning

RangeParameter is actually a kind of Descriptor, not a Parameter. This naming may be confusing.

Deprecated since version 2.2.0: RangeParameter has been renamed RangeDescriptor. Use RangeDescriptor instead.

Parameters:

• max_val – the minimum value
• min_val – the maximum value

class parameters.WeatherParameter(WeatherSelector, value_descriptors: Union[besos.IO_Objects.Descriptor, List[besos.IO_Objects.Descriptor]] = None, name='')

Parameter to describe weather file values

transformation_function(epw, value_dict) → None

Mutates the epw based on the value provided.

class parameters.WeatherSelector(column_name, time_params=None, func=None)

Selector used for epw files

Parameters:

• column_name – The column of values in epw ex: ‘Dry Bulb Temperature’
• time_params – Dictionary of time parameters to meet ex: ‘{‘Month’:[‘1’,’2’,’3’]}’

addition(epw, val)

Adds val to each dataframe value

Parameters:

• epw – the weather object to modify.
• val – the value to add on the dataframes value

Returns:

epw object

get(epw)

Get the current value of this attribute of the building

Parameters:epw – weather object Returns:list of values from the weather_data

multiply(epw, factor)

Multiplies the dataframe value with the factor

Parameters:

• epw – the weather object to modify.
• factor – the factor to multiply the dataframe value with

Returns:

epw object

set(epw, values=None)

Sets value in the epw dataframe

Parameters:

• epw – the weather object to modify.
• values – the value or values to set this selector’s attribute to.

Returns:

epw object

parameters.expand_plist(pList: Dict[str, Dict[str, Tuple[float, float]]]) → List[T]

This function expands a nested dictionary of the correct format into a list of inputs.

The dictionary should have the format: {‘idf object name’: {‘idf object1 property name’: (min_value, max_value)}

Both layers of the dictionaries can have as many names as desired

parameters.wwr(value_descriptor=None, **kwargs) → parameters.Parameter

Makes a window-to-wall-ratio parameter.

Parameters:value_descriptor – a parameter describing the valid window-wall-ratios Defaults to RangeDescriptor(0.01, 0.99, name=”Window to Wall Ratio”) Returns:Parameter

class parameters.wwrSelector

Selector for window to wall ratio.

get(building)

Get the current value of this attribute of the building

Parameters:building – Returns:

set(building, value)

Sets the window to wall ratio of the building to the provided value

Parameters:

• building – the building to modify
• value – the value of the wwr

setup(building) → None

Adjusts the building to have at most one window per wall, making it ready to have its window to wall ratio modified.

Parameters:building – The building to adjust