Project

Project

Project(name, sim)

Bases: Parameter_container

Project has the following features:

  • It is included in the Simulation environment
  • Contain a list of components
  • Contains parameters for its definition
  • Contains Environment_3D for 3D representation of the project

Projects are created with Simulation.new_project(), not directly. Their parameters (time_step, n_time_steps, initial_time, simulation_file_met, shadow_calculation...) are described in the user guide.

Create new project

Parameters:

Name Type Description Default
name str

name of the project

required
sim Simulation

parent Simulation environment

required

clear

clear()

Remove every component from the Project

The parameters of the project itself keep their values; only its components are dropped. Needed before reloading a definition into a project that already holds one, because read_dict() and read_json() add components, they do not replace them.

del_component

del_component(component)

Delete component from Project

Parameters:

Name Type Description Default
component Component

Component to be removed from the project

required

component

component(name)

Find and return component with its name

Parameters:

Name Type Description Default
name str

name of the component

required

Returns:

Type Description
Component

component found, None if not found.

component_list

component_list(comp_type='all')

Components list in the project

Parameters:

Name Type Description Default
comp_type str

Type of the components to include ("Space", "Building_surface"...), "all" for every component. Defaults to "all".

'all'

Returns:

Type Description
list of Component

Components of the project, in definition order.

component_dataframe

component_dataframe(comp_type='all', string_format=False)

Parameters of the components as a table

Parameters:

Name Type Description Default
comp_type str

Type of the components to include; with "all" only name, type and description are shown, with a type every parameter of that type. Defaults to "all".

'all'
string_format bool

Convert every value to string. Defaults to False.

False

Returns:

Type Description
DataFrame

One row per component, one column per parameter.

new_component

new_component(comp_type, name)

Create a new component and add it to the project

Parameters:

Name Type Description Default
comp_type str

Type (class name) of the component, e.g. "Space".

required
name str

Name of the component.

required

Returns:

Type Description
Component

The new component with its default parameters, None if the type does not exist.

duplicate_component

duplicate_component(component_name, new_name)

Duplicate an existing component with a new name

Parameters:

Name Type Description Default
component_name str

name of the component to duplicate

required
new_name str

name for the new component

required

Returns:

Type Description
Component

the new duplicated component, None if error

read_dict

read_dict(dict)

Load parameters and components from a dictionary, then check the project

Components are added to the ones already in the project (see clear()).

Parameters:

Name Type Description Default
dict dict

dictionary with the parameters of the project and the list of its components in the key "components"

required

write_dict

write_dict()

Write dictionary with the definition of the project

Returns:

Type Description
dict

dictionary with the parameters and components that define the project, in the format read by read_dict()

read_json

read_json(json_file)

Load parameters and components from a json file, then check the project

Parameters:

Name Type Description Default
json_file str

file with the dictionary of the project (format of read_dict())

required

write_json

write_json(json_file)

Write project definition to json file

Parameters:

Name Type Description Default
json_file str

file name

required

check

check()

Check if all is correct, for the project and all its components

Prints all errors found

Returns:

Type Description
list of Message

errors found

simulate

simulate(progress=None)

Run the time simulation of the project

Orders the components, runs pre_simulation() on them and then, for each of the n_time_steps time steps, the pre-iteration, the iterations until every component converges (at most n_max_iteration) and the post-iteration. Results are stored in the variables of the components.

The progress is printed with a tqdm bar; progress reports it elsewhere as well, such as a progress bar of a notebook or an app.

Parameters:

Name Type Description Default
progress callable

called after each time step as progress(step, n_time_steps), with step from 1 to n_time_steps. Defaults to None.

None

dates

dates()

Dates of the simulation time steps

Returns:

Type Description
numpy.ndarray of datetime

Date of each time step, centered in the interval (for hourly steps, 00:30, 01:30...).

simulation_dataframe

simulation_dataframe()

Information of the last simulation, one row per time step

Returns:

Type Description
DataFrame

Date, number of iterations, convergence and last component that did not converge of each time step.

editor

editor()

Interactive editor for the whole project definition.

Returns an anywidget that works in Jupyter and, wrapped in mo.ui.anywidget(), in Marimo. The document is read with write_dict(); the widget does not write back to this project.

Returns:

Type Description
ProjectEditor

widget holding the project document in .value

results

results(*variables, height=600, chart_height=300, show_3d=False)

Interactive viewer of the simulation results.

Returns an anywidget that works in Jupyter and, wrapped in mo.ui.anywidget(), in Marimo: the variables of the components are listed on the left and the selected ones plotted on the right, one chart per unit, with the frequency, aggregation and interval chosen in its toolbar.

Parameters:

Name Type Description Default
*variables str

variables to show from the start, as "component.variable", e.g. "spaces_1.temperature".

()
height int

height of the whole widget, in pixels. Defaults to 600.

600
chart_height int

height of each chart, in pixels. Defaults to 300.

300
show_3d bool

show the 3D view of the project above the charts; clicking a surface there opens its variables. Defaults to False.

False

Returns:

Type Description
ResultsViewer

widget; its dataframe() method returns what it shows.

create_3D_environment

create_3D_environment(env_3D)

Add the polygons of the project's surfaces and openings to a 3D environment

Parameters:

Name Type Description Default
env_3D Environment_3D

environment the polygons are added to

required

geometry_dict

geometry_dict()

Geometry of the project as plain data, for a 3D viewer

Returns:

Type Description
dict

{"meshes": [...], "spaces": [...]}, one mesh per polygon with its triangles and the component and spaces it belongs to

show_3D

show_3D()

Show the 3D geometry of the project (Plotly)

plotly_figure_3D

plotly_figure_3D()

The Plotly figure of show_3D(), returned instead of shown, so it can be composed, saved, or otherwise reused.

show_3D_shadows

show_3D_shadows(date)

Show the 3D geometry with the shadows of the sun at a date (Plotly)

Parameters:

Name Type Description Default
date datetime

date and time; at night a warning is shown instead

required

show_3D_shadows_animation

show_3D_shadows_animation(date)

Show an hourly animation of the shadows of the sun along a day (Plotly)

Parameters:

Name Type Description Default
date datetime

day of the animation (the time is ignored)

required