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
|
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 |