Skip to content

How to set up a workflow configuration for Radiance simulation?

What is a workflow configuration?

A workflow configuration is an instance of the WorkflowConfig class. It is used to run a two- or three- or five-Phase method simulation in Radiance.

The workflow configuration has two parts:

  1. settings

    • i.e number of parallel processes, epw/wea file, latitude, longitude, matrices sampling parameters, and etc.
    • See the Settings class for more details.

  2. model

    • i.e. scene, windows, materials, sensors, and views
    • See the Model class for more details.

How to set up a workflow configuration?

Method 1

Create instances of the Settings and Model classes to represent the settings and model parameters. Then, pass the Settings and Model instances into the WorkflowConfig class to generate a workflow configuration.

Method 2

Use WorkflowConfig.from_dict() to generate a workflow configuration by passing in a dictionary that contains the settings and model parameters.

0. Import the required classes and functions

import frads as fr

Method 1

1.1 Create an instance of Settings class

Create an instance of the Settings class
settings = fr.Settings()
Default setting

name The name of the simulation. (default="")

num_processors: The number of processors to use for the simulation. (default=1)

method: The Radiance method to use for the simulation. **(default="3phase")

overwrite: Whether to overwrite existing files. (default=False)

save_matrices: Whether to save the matrices generated by the simulation. (default=False)

sky_basis: The sky basis to use for the simulation. (default="r1")

window_basis: The window basis to use for the simulation. (default="kf")

non_coplanar_basis: The non-coplanar basis to use for the simulation. (default="kf")

sun_basis: The sun basis to use for the simulation. (default="r6")

sun_culling: Whether to cull suns. (default=True)

separate_direct: Whether to separate direct and indirect contributions. (default=False)

epw_file: The path to the EPW file to use for the simulation. (default="")

wea_file: The path to the WEA file to use for the simulation. (default="")

start_hour: The start hour for the simulation. (default=8)

end_hour: The end hour for the simulation. (default=18)

daylight_hours_only: Whether to simulate only daylight hours. (default=True)

latitude: The latitude for the simulation. (default=37)

longitude: The longitude for the simulation. (default=122)

timezone: The timezone for the simulation. (default=120)

orientation: sky rotation. (default=0)

site_elevation: The elevation for the simulation. (default=100)

sensor_sky_matrix: The sky matrix sampling parameters. (default_factory=lambda: ["-ab", "6", "-ad", "8192", "-lw", "5e-5"])

view_sky_matrix: View sky matrix sampling parameters. (default_factory=lambda: ["-ab", "6", "-ad", "8192", "-lw", "5e-5"])

sensor_sun_matrix: Sensor sun matrix sampling parameters. (Default_factory=lambda: [ "-ab", "1", "-ad", "256", "-lw", "1e-3", "-dj", "0", "-st", "0"])

view_sun_matrix: View sun matrix sampling parameters.(default_factory=lambda: ["-ab", "1", "-ad", "256", "-lw", "1e-3", "-dj", "0", "-st", "0"])

sensor_window_matrix: Sensor window matrix sampling parameters. (default_factory=lambda: ["-ab", "5", "-ad", "8192", "-lw", "5e-5"])

view_window_matrix: View window matrix sampling parameters. (default_factory=lambda: ["-ab", "5", "-ad", "8192", "-lw", "5e-5"])

daylight_matrix: Daylight matrix sampling parameters. (default_factory=lambda: ["-ab", "2", "-c", "5000"])

Edit default setting parameters
# Edit the number of parallel processes
settings.num_processors = 4

# Provide a wea file
settings.wea_file = "oak.wea"

1.2 Create an instance of Model class

The Model class requires the following parameters:

  • scene: An instance of the SceneConfig class.
  • windows: A dictionary of instances of the WindowConfig class.
  • materials: An instance of the MaterialConfig class.
  • sensors: A dictionary of instances of the SensorConfig class.
  • views: A dictionary of instances of the ViewConfig class.

1.2.1 Scene

Create an instance of the SceneConfig class
scene = fr.SceneConfig(
    files=[
    "walls.rad",
    "ceiling.rad",
    "floor.rad",
    "ground.rad",
    ]
)
Scene geometry primitive example

walls.rad 

wall_mat polygon wall_1
0
0
12 
    0   0   0
    0   0   3
    0   3   3
    0   3   0

1.2.2 Windows

Create an instance of the WindowConfig class
window1 = fr.WindowConfig(
    file="window1.rad", # window geomtry primitive file
    matrix_name="window1_matrix" # specified in materials 
)
Window geometry primitive example

window1.rad 

window_mat polygon window1
0
0
12 
    0   1   1
    0   1   2
    0   2   2
    0   2   1

1.2.3 Materials

Create an instance of the MaterialConfig class
materials = fr.MaterialConfig(
    files=["materials.mat"], # material primitive file
    matrices={
        "window1_matrix": {"matrix_file": "window1_bsdf.xml"}
        } # window matrix file
)
Materials primitive example

materials.mat 

void plastic wall_mat
0
0
5 0.5 0.5 0.5 0 0

1.2.4 Sensors

Create an instance of the SensorConfig class
sensor1 = fr.SensorConfig(file="grid.txt") # a file of sensor points

sensor_view1 = fr.SensorConfig(
    data=[[1, 1, 1, 0, -1, 0]]
) # a sensor point at (1, 1, 1) with a view direction of (0, -1, 0)
Sensor points example

grid.txt

x_viewpoint y_viewpoint z_viewpoint x_direction y_direction z_direction 

0 1 1 0 -1 0
0 1 2 0 -1 0

1.2.5 Views

view1 = fr.ViewConfig(file = "view1.vf")
View example

view1.vf

view_type view_point view_direction view_up_direction view_horizontal_field_of_view view_vertical_field_of_view view_rotation_angle 

-vta -vp 1 1 1 -vd 0 -1 0 -vu 0 0 1 -vh 180 -vv 180

1.2.6 Create an instance of the Model class

Tip

  • All phases require materials
  • All phases require sensors or views
  • Three- and Five-Phase methods require windows
  • If a window matrix name is specified in windows, the corresponding window matrix file must be specified in materials
  • There is a corresponding sensors point for each views point. This sensors point could be automatically generally when views is specified in Model or manually defined by the user as shown below. view1 in sensors must have the same view direction and view position as view1 in views; otherwise, an error will be raised.
model = fr.Model(
    scene=scene,
    windows={"window1": window1},
    materials=materials,
    sensors={"sensor1": sensor1, "view1": sensor_view1}, # view1 is a sensor point corresponding to view1 in views
    views={"view1": view1}
)

1.3 Pass Settings and Model instances into WorkflowConfig class

cfg = fr.WorkflowConfig(settings, model)

Method 2

2. Pass a dictionary into the WorkflowConfig.from_dict() method

The dictionary should contain the settings and model parameters.

dictionary example 
dict1 = {
    "settings": {
        "method": "3phase",
        "sky_basis": "r1",
        "epw_file": "",
        "wea_file": "oak.wea",
        "sensor_sky_matrix": ["-ab", "0"],
        "view_sky_matrix": ["-ab", "0"],
        "sensor_window_matrix": ["-ab", "0"],
        "view_window_matrix": ["-ab", "0"],
        "daylight_matrix": ["-ab", "0"],
    },
    "model": {
        "scene": {
            "files": ["walls.rad", "ceiling.rad", "floor.rad", "ground.rad"]
        },
        "windows": {
            "window1": {
                "file": "window1.rad",
                "matrix_name": "window1_matrix",
            }
        },
        "materials": {
            "files": ["materials.mat"],
            "matrices": {"window1_matrix": {"matrix_file": "window1_bsdf.xml"}},
        },
        "sensors": {
            "sensor1": {"file": "sensor1.txt"},
            "view1": {"data": [[1, 1, 1, 0, -1, 0]]},
        },
        "views": {"view1": {"file": "view1.vf"}},
    },
}

cfg = fr.WorkflowConfig.from_dict(dict1)

Use an EnergyPlus model to set up a workflow configuration

You can use the epjson_to_rad() function to convert an EnergyPlus model to a Radiance model. The function returns a dictionary of the Radiance model for each exterior zone in the EnergyPlus model. You can use the dictionary to set up the workflow configuration.

epmodel = fr.EnergyPlusModel("file.idf") # EnergyPlus model
radmodel = fr.epjson_to_rad(epmodel) # Radiance model
dict_zone1 = radmodel["zone1"] # Dictionary of zone1

cfg = fr.WorkflowConfig.from_dict(dict_zone1)