SOBA Documentation¶

SOBA Overview¶

SOBA. is a new system of Simulation of Occupancy Based on Agents implemented in Python., which has become an increasingly popular language for scientific computing.

This software is useful for conducting studies based on occupancy simulations, mainly in buildings, such as drill simulation or energy studies.

The simulations are configured by declaring one or more types of occupants, with specific and definable behavior, a physical space (rooms of the building) and agents that are interconnected with each other and with the occupants. The simulation and results can be evaluated both in real time and post-simulation.

It is provided as open source software:

Github repository: https://github.com/gsi-upm/soba

Arquitecture Description¶

SOBA is implemented through 5 modules which group independent components with a related function.

Module Model.
- Model. This component is the core of the simulations. The model creates and manages space and agents, provides a scheduler that controls the agents activation regime, stores model-level parameters and serves as a container for the rest of components.
- Time. Component of time management during the simulation in sexagesimal units and controller of the scheduler during the simulation.
Module Agents.
- Agent. Base class to define any type of agent, which performs actions and interactions within a model.
- Occupant. An object of the Occupant class is a type of agent developed and characterized to simulate the behavior of crowds in buildings.
- Occupancy module.
  
  Markov.
  
  AStar. Auxiliar class used by the occupants to move in the building.
  
  FOV.This component is a permissive field of view, which is useful to define the occupant visibility.
- Transitions. This external package is a lightweight, object-oriented state machine implementation in Python.
Module Space.
- Grid. The space where the agents are situated and where they perform their actions is defined by means of a grid with coordinates (x, y).
- ContinuousItems / RoomsItems. Various classes that define the representation of physical space objects in the model.
Module Visualization. Two components provide a simple mechanism to represent the model in a web interface, based on HTML rendering though a server interface, implemented with web sockets.
Module Launchers. The simulation will be executed defining a type of perfomance: in bacth or with visual representation.

How install¶

Pip instalation¶

$ pip install soba

Github repository¶

https://github.com/gsi-upm/soba

Introductory Tutorial¶

Instalation¶

First of all, you need to install the package using pip.

$ pip install soba

In case of error, this other command should be used, ensuring to have installed python 3 and pip 3.

$ pip3 install soba

Tutorial¶

The SOBA tool can be provided to be used directly on two scenarios:

Generic case with a space defined as a grid of a given square size (by default, half a meter on each side).
Simplified case with a room defined by rooms, to perform simulations in simplified buildings that require less consumption of resources and specifications.

An introductory tutorial will be presented for each case, although most parameters are common or similar.

SOBA enables the performance of the simulations in two modes:

With visual representation.
In batch mode.

In the tutorials, the small modifications required to use each posibility are reflected.

IMPORTANT NOTE: The .py files described in this tutorial are available in the github repository https://github.com/gsi-upm/soba/tree/master/projects/basicExamples

Implementing a sample model with continuous space¶

Once soba is installed, the implementation can be started. First we define the generic parameters to both types of scenario.

1.- We define the characteristics of the occupants

from collections import OrderedDict
#JSON to store all the informacion.
jsonsOccupants = []

#Number of occupants
N = 12

#Definition of the states
states = OrderedDict([('Leaving','out'), ('Resting', 'sofa'), ('Working in my laboratory', 'wp')])

#Definition of the schedule
schedule = {'t1': "09:00:00", 't2': "13:00:00", 't3': "14:10:00"}

#Possible Variation on the schedule
variation = {'t1': "00:10:00", 't2': "01:20:00", 't3': "00:20:00"}

#Probability of state change associated with the Markovian chain as a function of the temporal period.
markovActivity = {
    '-t1': [[100, 0, 0], [0, 0, 0], [0, 0, 0]],
    't1-t2': [[30, 40, 30], [0, 50, 50], [0, 50, 50]],
    't2-t3': [[0, 0, 0], [50, 50, 0], [0, 0, 0]],
    't3-': [[0, 50, 50], [10, 90, 0], [0, 0, 0]]
}

#Time associated to each state (minutes)
timeActivity = {
    '-t1': [60, 0, 0], 't1-t2': [2, 60, 15], 't2-t3': [60, 10, 15], 't3-': [60, 20, 15]
}

#Store the information
jsonOccupant = {'type': 'example' , 'N': N, 'states': states , 'schedule': schedule, 'variation': variation, 'markovActivity': markovActivity, 'timeActivity': timeActivity}
jsonsOccupants.append(jsonOccupant)

2.- We define the building plan or the distribution of the space.

import soba.visualization.ramen.mapGenerator as ramen

with open('labgsi.blueprint3d') as data_file:
    jsonMap = ramen.returnMap(data_file)

3.- We implement a Model inheriting a base class of SOBA.

from soba.model.model import ContinuousModel
import datetime as dt

class ModelExample(ContinuousModel):

    def __init__(self, width, height, jsonMap, jsonsOccupants, seed = dt.datetime.now()):
        super().__init__(width, height, jsonMap, jsonsOccupants, seed = seed)

    def step(self):
        if self.clock.clock.day > 3:
            self.finishSimulation = True
        super().step()

4.- We call the execution methods.

4.1-With visual representation.

import soba.run

soba.run.run(ModelExample, [], cellW, cellH, jsonMap, jsonsOccupants)

4.1- Bacth mode.

#Fixed parameters during iterations
fixed_params = {"width": cellW, "height": cellH, "jsonMap": jsonMap, "jsonsOccupants": jsonsOccupants}
#Variable parameters to each iteration
variable_params = {"seed": range(10, 500, 10)}

soba.run.run(ModelExample, fixed_params, variable_params)

Implementing a sample model with simplified space¶

Once soba is installed, the implementation can be started. First we define the generic parameters to both types of scenario.

1.- We define the characteristics of the occupants

from collections import OrderedDict
#JSON to store all the informacion.
jsonsOccupants = []

#Number of occupants
N = 3

#Definition of the states
states = OrderedDict([('out','Pos1'), ('Working in my laboratory', {'Pos2': 1, 'Pos3': 2})])

#Definition of the schedule
schedule = {'t1': "09:00:00", 't2': "13:00:00", 't3': "14:10:00"}

#Possible Variation on the schedule
variation = {'t1': "00:10:00", 't2': "01:20:00", 't3': "00:20:00"}

#Probability of state change associated with the Markovian chain as a function of the temporal period.
markovActivity = {
    '-t1': [[100, 0], [0, 0]],
    't1-t2': [[50, 50], [0, 0]],
    't2-t3': [[0, 0], [50, 0]],
    't3-': [[0, 50], [10, 90]]
}

#Time associated to each state (minutes)
timeActivity = {
    '-t1': [60, 0],
    't1-t2': [2, 60],
    't2-t3': [60, 10],
    't3-': [60, 20]
}

#Store the information
jsonOccupant = {'type': 'example' , 'N': N, 'states': states , 'schedule': schedule, 'variation': variation,
                'markovActivity': markovActivity, 'timeActivity': timeActivity}
jsonsOccupants.append(jsonOccupant)

2.- We define the building plan or the distribution of the space.

jsonMap = {
  'Pos1': {'entrance':'', 'conectedTo': {'U':'Pos2'}, 'measures': {'dx':2, 'dy':2}},
  'Pos2': {'measures': {'dx':3, 'dy':3.5}, 'conectedTo': {'R':'Pos3'}},
  'Pos3': {'measures': {'dx':3, 'dy':3.5}}
}

3.- We implement a Model inheriting a base class of SOBA.

from soba.model.model import ContinuousModel
import datetime as dt

class ModelExample(RoomsModel):

    def __init__(self, width, height, jsonMap, jsonsOccupants, seed = dt.datetime.now()):
        super().__init__(width, height, jsonMap, jsonsOccupants, seed = seed)

    def step(self):
        if self.clock.clock.day > 3:
            self.finishSimulation = True
        super().step()

4.- We call the execution methods. 4.1- With visual representation.

cellW = 4
cellH = 4

soba.run.run(ModelExample, [], cellW, cellH, jsonMap, jsonsOccupants)

4.1- Bacth mode.

#Fixed parameters during iterations
fixed_params = {"width": cellW, "height": cellH, "jsonMap": jsonMap, "jsonsOccupants": jsonsOccupants}
#Variable parameters to each iteration
variable_params = {"seed": range(10, 500, 10)}

soba.run.run(ModelExample, fixed_params, variable_params)

Running the simulation using the terminal¶

$ python exampleContinuous.py -v

Options:

-v,     Visual option on browser

-b,     Background option

-r,     Ramen option

APIs¶

Model Module Documentation¶

Model¶

Time Control¶

Agents Module Documentation¶

Agent¶

class agent.Agent(unique_id, model)¶

Base class to create Agent objects. The agents are controlled by the scheduler of the Model associated.

Attributes:: model: Model associated to the agent. unique_id: Unique id of the agent. color: Color with which the agent will be represented in the visualization.
Methods:: step: Method invoked by the Model scheduler in each step. Step common to all Agents.

step()¶: Method invoked by the Model scheduler in each step. Step common to all Agents.

Occupant¶

Agent Modules¶