API documentation¶

Model class¶

class cobs.model.Agent[source]¶

Bases: object

Dummy agent as a placeholder. No meaning

class cobs.model.Model(idf_file_name: str = None, prototype: str = None, climate_zone: str = None, weather_file: str = None, heating_type: str = None, foundation_type: str = None, agent: cobs.model.Agent = None, reward=None, eplus_naming_dict=None, eplus_var_types=None, buffer_capacity=None, buffer_seed=None, buffer_chkpt_dir=None, tmp_idf_path=None)[source]¶

Bases: object

The environment class.

add_configuration(idf_header_name: str, values: dict = None)[source]¶

Create and add a new component into the building model with the specific type and setting values.

Parameters

idf_header_name – The type of the component.
values – A dictionary map the setting entry and the setting value.

Returns

The new component.

add_state_modifier(model)[source]¶

Add a state modifier model, including predictive model, state estimator, controller, etc.

Parameters: model – A class object that follows the template (contains step(true_state, environment) method).
Returns: None

add_state_values(entry)[source]¶

Add entries to the state. If selected entry is not available for the current building, it will be ignored.

Parameters: entry – Entry names that the state of the environment should have.
Returns: None.

delete_configuration(idf_header_name: str, component_name: str = None)[source]¶

Delete an existing component from the building model.

Parameters

idf_header_name – The type of the component.
component_name – The entry of the component.

Returns

None.

edit_configuration(idf_header_name: str, identifier: dict, update_values: dict)[source]¶

Edit an existing component in the building model.

Parameters

idf_header_name – The type of the component.
identifier – A dictionary map the setting entry and the setting value to locate the target component.
update_values – A dictionary map the setting entry and the setting value that needs to update.

Returns

None.

flatten_state(order, state=None)[source]¶

Flatten the state to a list of values by a given order.

Parameters

order – The order that the values should follow.
state – The state to flatten. If not specified, then the current state is selected.

Returns

List of values follows the given order.

get_all_configurations()[source]¶

Read the IDF file, and return the content formatted with the IDD file.

Returns: the full IDF file with names and comments aside.

get_available_names_under_group(idf_header_name: str)[source]¶

Given the type of components, find all available components in the building by their entry.

Parameters: idf_header_name – The type of the component.
Returns: List of names.

get_blinds()[source]¶

Get the zone-blind matching dictionary based on the IDF file.

Returns: A dictionary where key is the zone name, and the value is a set of blind available in the zone.

get_configuration(idf_header_name: str, component_name: str = None)[source]¶

Given the type of component, the entry of the target component, find the settings of that component.

Parameters

idf_header_name – The type of the component.
component_name – The entry of the component.

Returns

Settings of this component.

get_current_state_values()[source]¶

Find the current entries in the state.

Returns: List of entry names that is currently available in the state.

get_date()[source]¶

Get the current time in the simulation environment.

Returns: None

get_doors()[source]¶

Get the zone-door matching dictionary based on the IDF file.

Returns: A dictionary where key is the zone name, and the value is a set of door available in the zone.

get_lights()[source]¶

Get the zone-light matching dictionary based on the IDF file.

Returns: A dictionary where key is the zone name, and the value is a set of light available in the zone.

get_link_zones()[source]¶

Generate a graph that shows the connectivity of zones of the current building.

Returns: A bi-directional graph represented by a dictionary where the key is the source zone name and the value is a set of all neighbor zone name.

get_possible_actions()[source]¶

Get all available actions that the user-defined agent can take. This list of actions only depends on the building architecture.

Returns: List of available actions in dictionaries.

get_possible_state_entries()[source]¶

Get all available state entries. This list of entries only depends on the building architecture.

Returns: List of available state entry names.

get_sub_configuration(idf_header_name: str)[source]¶

Show all available settings for the given type of component.

Parameters: idf_header_name – The type of the component.
Returns: List of settings entry.

get_total_timestep()[source]¶

get_value_range(idf_header_name: str, field_name: str, validate: bool = False)[source]¶

Get the range of acceptable values of the specific setting.

Parameters

idf_header_name – The type of the component.
field_name – The setting entry.
validate – Set to True to check the current value is valid or not.

Returns

Validation result or the range of all acceptable values retrieved from the IDD file.

get_windows()[source]¶

Get the zone-window matching dictionary based on the IDF file.

Returns: A dictionary where key is the zone name, and the value is a set of window available in the zone.

is_terminate()[source]¶

Determine if the simulation is finished or not.

Returns: True if the simulation is done, and False otherwise.

list_all_available_configurations()[source]¶

Generate a list of all type of components appeared in the current building.

Returns: list of components entry.

model_import_flag = False¶

static name_reformat(name)[source]¶

Convert the entry from the space separated entry to the underline separated entry to match the IDF.

Parameters: name – The space separated entry.
Returns: The underline separated entry.

pop_state_values(index)[source]¶

Remove entries from the state by its index. If selected index is not available in the state, it will be ignored.

Parameters: index – Entry index that the state of the environment should not have.
Returns: All entry names that is removed.

remove_state_values(entry)[source]¶

Remove entries from the state. If selected entry is not available in the state, it will be ignored.

Parameters: entry – Entry names that the state of the environment should not have.
Returns: None.

reset()[source]¶

Clear the actions and buffer, reset the environment and start the simulation.

Returns: The initial state of the simulation.

sample_buffer(batch_size)[source]¶

Sample a batch of experience from the replay buffer.

Parameters: batch_size – Number of entries in a batch.
Returns: (state, action, next state, is terminate)

sample_flattened_buffer(order, batch_size)[source]¶

Sample a batch of experience from the replay buffer and flatten the states by a given order.

Parameters

order – The order that the values should follow.
batch_size – Number of entries in a batch.

Returns

(state, action, next state, is terminate) where states are flatten.

save_idf_file(path: str)[source]¶

Save the modified building model for EnergyPlus simulation

Parameters: path – The relative path to the modified IDF file.
Returns: None.

select_state_values(entry=None, index=None)[source]¶

Select interested state entries. If selected entry is not available for the current building, it will be ignored.

Parameters

entry – Entry names that the state of the environment should have.
index – Index of all available entries that the state of the environment should have.

Returns

None.

set_blinds(windows, blind_material_name=None, shading_control_type='AlwaysOff', setpoint=50, agent_control=False)[source]¶

Install blinds that can be controlled on some given windows.

Parameters

windows – An iterable object that includes all windows’ name that plan to install the blind.
blind_material_name – The name of an existing blind in the IDF file as the blind for all windows.
shading_control_type – Specify default EPlus control strategy (only works if control=False)
setpoint – Specify default blind angle.
agent_control – False if using a default EPlus control strategy or no control (ie blinds always off). True if using an external agent to control the blinds.

Returns

None

classmethod set_energyplus_folder(path)[source]¶

Add the pyenergyplus into the path so the program can find the EnergyPlus.

Parameters: path (str) – The installation path of the EnergyPlus 9.3.0.
Returns: None

set_occupancy(occupancy, locations)[source]¶

Include the occupancy schedule generated by the OccupancyGenerator to the model as the occupancy data in EnergyPlus simulated environment is broken.

Parameters

occupancy – Numpy matrix contains the number of occupanct in each zone at each time slot.
locations – List of zone names.

Returns

None

set_runperiod(days, start_year: int = 2000, start_month: int = 1, start_day: int = 1, specify_year: bool = False)[source]¶

Set the simulation run period.

Parameters

days – How many days in total the simulation should perform.
start_year – Start from which year
start_month – Start from which month of the year
start_day – Start from which day of the month
specify_year – Use default year or a specific year when simulation is within a year.

Returns

None

set_timestep(timestep_per_hour)[source]¶

Set the timestep per hour for the simulation.

Parameters: timestep_per_hour – How many timesteps within a hour.
Returns: None

simulate(terminate_after_warmup=False)[source]¶

Run the whole simulation once. If user use this method instead of the reset function, the user need to provide the Agent.

Parameters: terminate_after_warmup – True if the simulation should terminate after the warmup.
Returns: None.

step(action_list=None)[source]¶

Add all actions into the EventQueue, and then generate the state value of the next timestep.

Parameters: action_list – list of dictionarys contains the arguments for EventQueue.schedule_event().
Returns: The state value of the current timestep.

class cobs.model.Reward[source]¶

Bases: object

Dummy reward as a placeholder. No meaning

ReplayBuffer class¶

class cobs.replay_buffer.ReplayBuffer(capacity=None, seed=None, chkpt_dir=None)[source]¶

Bases: object

load(num)[source]¶

Load a dumped buffer from the local disk.

Parameters: num – unique identifier to specify the version of the buffer dump.
Returns: None

push(prev_state, prev_action, current_state, done)[source]¶

Add one step into the buffer.

Parameters

prev_state – The state before performing an action.
prev_action – The action current step performed.
current_state – The resulting state after the action is being evaluated.
done – The current_state is terminate state or not.

Returns

None

reset()[source]¶

Clear the buffer.

Returns: None

sample(batch_size)[source]¶

Sample some experiences from the buffer.

Parameters: batch_size – Number of steps to sample.
Returns: four lists for previous_state, action, resulting_state, terminate, respectively.

save(num)[source]¶

Dump the current buffer to local disk.

Parameters: num – unique identifier to specify the version of the buffer dump.
Returns: None

set_ignore(ignore_set)[source]¶

Set which state features should not be stored to save memory space.

Parameters: ignore_set – A set contains all the key of state features that should be ignored.
Returns: None

terminate()[source]¶

Set the last added state to terminate state.

Returns: None

OccupancyGenerator Class¶

class cobs.occupancy_generator.OccupancyGenerator(model, num_occupant=10, random_seed=None)[source]¶

Bases: object

This class use the queueing system to generate the occupancy schedule TODO: Add occupancy actions

generate_all_people_daily_movement()[source]¶

Generate a list of Person objects and simulate the movement for each person.

Returns: list of Person objects.

generate_daily_schedule(add_to_model=True, overwrite_dict=None)[source]¶

Generate a numpy matrix contains the locations of all occupants in the day and add tp the model.

Parameters

add_to_model – Default is True. If False, then only generate the schedule in numpy and IDF format but not save to the model automatically.
overwrite_dict – Default is None. If set to a dict with {zone_name: old_people_object_name}, it will overwrite existing People instead of creating a new one

Returns

Three objects, (IDF format schedule, numpy format schedule, list of all accessble locations in the building).

generate_light(input_name=None)[source]¶

get_path(start, end)[source]¶

Use BFS to find the shortest path between two zones.

Parameters

start – The entry of the start zone.
end – The entry of the target zone.

Returns

A list of zone names that the occupant need to cross.

initialize_light_config()[source]¶

save_light_config(output_name=None)[source]¶

class cobs.occupancy_generator.Person(generator, office=None)[source]¶

Bases: object

This class contains the detail location of a single occupant.

check_in_office(start, end)[source]¶

Determine if the occupant is in his/her office or not during a given period of time.

Parameters

start – The start time.
end – The end time.

Returns

Return True if the occupant is in his/her office between given time, and False otherwise.

customer_come(start_time, end_time, dest)[source]¶

Simulate the event of customers coming for the current occupant.

Parameters

start_time – The scheduled appointment start time (not the real start time).
end_time – The scheduled appointment end time (not the real end time).
dest – The appointment location (zone entry).

Returns

None

decide_come()[source]¶

Each person need to decide if he/she will come to work today, when exactly they come, and when exactly they leave. We assume people start to come at 8:30 am and leave at 5 pm, with a poisson arrival lambda = 30 min. Notice that we simulate this as poisson arrival, which means two arrivals are not independent.

Returns: True if come to work, False otherwise

generate_daily_meeting()[source]¶

Generate the time that current occupant go to the daily meeting.

Returns: None

generate_daily_route(customer_list)[source]¶

Generate the whole day locations for the occupant.

Parameters: customer_list – List of Person that will visit the occupant today.
Returns: List of appointment times.

generate_go_other_office()[source]¶

Generate the event of visiting colleagues’ office for random talk. Only possible if the colleague is in the office.

Returns: None.

generate_lunch()[source]¶

Generate the time that current occupant go to the cafeteria and take the lunch.

Returns: None

get_in_office_range()[source]¶: Find all times that the occupant is in his/her office. :return: list of timeslots that the occupant is in the office

get_position(sec)[source]¶

Get the location of the occupant at the given time

Parameters: sec – The time that need to check.
Returns: The zone entry of the location at the given time.

get_trigger()[source]¶

handle_customer(num_customer)[source]¶

Set up an appointment for occupant with some new customers.

Parameters: num_customer – Number of customers in total today will come.
Returns: tuple of (appointment start time, appointment end time, appointment location).

cobs.occupancy_generator.get_white_bias(second)[source]¶

Generate a bias.

Parameters: second – Value range.
Returns: Bias.

cobs.occupancy_generator.main()[source]¶

EventQueue class¶

class cobs.event_queue.EventQueue[source]¶

Bases: object

add_extra_events(value_name: str, priority: int, value, start_time: int, end_time: int = None, note: str = None)[source]¶

Add events/actions that is not for the EnergyPlus to run. This action is stored in a separate queue for other agents/predictive models/estimation models to use.

Parameters

value_name – Name of the action.
priority – An integer. Lower value indicates a higher priority.
value – Action value.
start_time – When this action will be triggered.
end_time – (Optional) When this action will stop.
note – (Optional) Placeholder for extra information.

Returns

None.

get_event(time: int)[source]¶

Get all events/actions that happens at a given time.

Parameters: time – Target time.
Returns: a dictionary contains all events/actions scheduled at the given time.

schedule_event(value, start_time: int, priority: int, type: str = 'actuator', dict_target: dict = None, component_type: str = None, control_type: str = None, actuator_key: str = None, var_name: str = None, end_time: int = None, note: str = None)[source]¶

Add events/actions that is for the EnergyPlus to run.

Parameters

value – Action value.
start_time – When this action will be triggered.
priority – An integer. Lower value indicates a higher priority.
type – One of actuator and global.
dict_target – A dictionay type of action contains the component_type, control_type, and actuator_key.
component_type – A string same as the EnergyPlus conponent type.
control_type – A string same as the EnergyPlus control type.
actuator_key – A string same as the EnergyPlus actuator name.
var_name – A string same as the EnergyPlus global controller name.
end_time – (Optional) When this action will stop.
note – (Optional) Placeholder for extra information.

Returns

None.

trigger(current_time: int)[source]¶

Get all events/actions that happens at a given time. In the meantime, lock all happened actions. No more actions can be scheduled before the given time.

Parameters: current_time – Target time.
Returns: a dictionary contains all events/actions scheduled at the given time.