How to create a simulation#

This tutorial demonstrates how to create a simulation.

What is a simulation?#

A simulation contains selected sensors, sources to model ray-trace in space.

[1]:
from pathlib import Path

from ansys.speos.core import GeoRef, Project, Speos
from ansys.speos.core.simulation import SimulationInteractive, SimulationInverse

# If using docker container
assets_data_path = Path("/app") / "assets"
# If using local server
# assets_data_path = Path().resolve().parent.parent / "tests" / "assets"
# If using a different path
# assets_data_path = Path("path/to/downloaded/example/assets")

Create connection with speos rpc server#

[2]:
speos = Speos(host="localhost", port=50098)

Create Project#

Create a new project first.

The only way to create a simulation is to create it from a project.

[3]:
p = Project(speos=speos)
print(p)
{
    "name": "",
    "description": "",
    "metadata": {},
    "part_guid": "",
    "sources": [],
    "sensors": [],
    "simulations": [],
    "materials": [],
    "scenes": []
}

Prepare prerequisites#

Create the necessary elements for a simulation: Sensor, source, root part, optical property are prerequisites.

Prepare the root part#

[4]:
root_part = p.create_root_part()
root_part.create_body(name="Body.1").create_face(name="Face.1").set_vertices(
    [0, 1, 2, 0, 2, 2, 1, 2, 2]
).set_facets([0, 1, 2]).set_normals([0, 0, 1, 0, 0, 1, 0, 0, 1])
root_part.commit()
[4]:
<ansys.speos.core.part.Part at 0x7f9eb2d5f460>

Prepare an optical property#

[5]:
opt_prop = p.create_optical_property("Material.1")
opt_prop.set_volume_opaque().set_surface_mirror()  # vop as opaque and sop as mirror
# Choose the geometry for this optical property : Body.1
opt_prop.set_geometries(geometries=[GeoRef.from_native_link(geopath="Body.1")])
opt_prop.commit()
[5]:
<ansys.speos.core.opt_prop.OptProp at 0x7f9eb2d5feb0>

Prepare an irradiance sensor#

[6]:
sensor1 = p.create_sensor(name="Irradiance.1")
# colorimetric or spectral so that the sensor can be used both in direct and inverse simulation
sensor1.set_type_colorimetric()
sensor1.commit()
[6]:
<ansys.speos.core.sensor.SensorIrradiance at 0x7f9eb2d5e080>

Prepare a surface source#

[7]:
source1 = p.create_source(name="Surface.1")
source1.set_exitance_constant(geometries=[(GeoRef.from_native_link(geopath="Body.1/Face.1"), True)])
# blackbody so that the source can be used both in direct and inverse simulation
source1.set_spectrum().set_blackbody()
source1.commit()
[7]:
<ansys.speos.core.source.SourceSurface at 0x7f9eb2da4af0>

Create a simulation#

[8]:
simulation1 = p.create_simulation(name="Simulation.1")
simulation1.set_sensor_paths(["Irradiance.1"]).set_source_paths(["Surface.1"])
print(simulation1)

simulation1.commit()
print(simulation1)
local: {
    "name": "Simulation.1",
    "sensor_paths": [
        "Irradiance.1"
    ],
    "source_paths": [
        "Surface.1"
    ],
    "description": "",
    "metadata": {},
    "simulation_guid": "",
    "simulation": {
        "direct_mc_simulation_template": {
            "geom_distance_tolerance": 0.01,
            "max_impact": 100,
            "weight": {
                "minimum_energy_percentage": 0.005
            },
            "dispersion": true,
            "colorimetric_standard": "CIE_1931",
            "fast_transmission_gathering": false,
            "ambient_material_uri": "",
            "stop_condition_rays_number": "200000",
            "automatic_save_frequency": 1800
        },
        "name": "Simulation.1",
        "description": "",
        "metadata": {},
        "scene_guid": "d1d733f2-9420-42f9-8b64-f607fda19cec",
        "simulation_path": "Simulation.1",
        "job_type": "CPU"
    }
}
{
    "name": "Simulation.1",
    "metadata": {
        "UniqueId": "e7b9cb87-125b-44d6-bc81-ad3426a05b5a"
    },
    "simulation_guid": "3a0d6d50-fac6-4df9-9d26-5c668e97416d",
    "sensor_paths": [
        "Irradiance.1"
    ],
    "source_paths": [
        "Surface.1"
    ],
    "description": "",
    "simulation": {
        "direct_mc_simulation_template": {
            "geom_distance_tolerance": 0.01,
            "max_impact": 100,
            "weight": {
                "minimum_energy_percentage": 0.005
            },
            "dispersion": true,
            "colorimetric_standard": "CIE_1931",
            "fast_transmission_gathering": false,
            "ambient_material_uri": "",
            "stop_condition_rays_number": "200000",
            "automatic_save_frequency": 1800
        },
        "name": "Simulation.1",
        "description": "",
        "metadata": {},
        "scene_guid": "d1d733f2-9420-42f9-8b64-f607fda19cec",
        "simulation_path": "Simulation.1",
        "job_type": "CPU"
    }
}

Set simulation characteristics#

Simulation is defined with the same default values as the GUI speos.

If the user would like to modify the simulation characteristics, it is possible to do so by setting the simulation characteristics as below.

[9]:
simulation2_direct = p.create_simulation(name="Simulation.2")

simulation2_direct.set_ambient_material_file_uri(
    uri=str(assets_data_path / "AIR.material")
).set_colorimetric_standard_CIE_1964().set_weight_none().set_geom_distance_tolerance(
    0.01
).set_max_impact(200).set_dispersion(False)
simulation2_direct.set_sensor_paths(["Irradiance.1"]).set_source_paths(["Surface.1"]).commit()
print(simulation2_direct)
{
    "name": "Simulation.2",
    "metadata": {
        "UniqueId": "0b3dca06-11f3-4501-8137-a9faf134b257"
    },
    "simulation_guid": "89e48372-4732-4d92-b797-cbaf7f8e2f36",
    "sensor_paths": [
        "Irradiance.1"
    ],
    "source_paths": [
        "Surface.1"
    ],
    "description": "",
    "simulation": {
        "direct_mc_simulation_template": {
            "geom_distance_tolerance": 0.01,
            "max_impact": 200,
            "colorimetric_standard": "CIE_1964",
            "ambient_material_uri": "/app/assets/AIR.material",
            "dispersion": false,
            "fast_transmission_gathering": false,
            "stop_condition_rays_number": "200000",
            "automatic_save_frequency": 1800
        },
        "name": "Simulation.2",
        "description": "",
        "metadata": {},
        "scene_guid": "d1d733f2-9420-42f9-8b64-f607fda19cec",
        "simulation_path": "Simulation.2",
        "job_type": "CPU"
    }
}

Read information#

Read simulation information

[10]:
print(simulation1)
{
    "name": "Simulation.1",
    "metadata": {
        "UniqueId": "e7b9cb87-125b-44d6-bc81-ad3426a05b5a"
    },
    "simulation_guid": "3a0d6d50-fac6-4df9-9d26-5c668e97416d",
    "sensor_paths": [
        "Irradiance.1"
    ],
    "source_paths": [
        "Surface.1"
    ],
    "description": "",
    "simulation": {
        "direct_mc_simulation_template": {
            "geom_distance_tolerance": 0.01,
            "max_impact": 100,
            "weight": {
                "minimum_energy_percentage": 0.005
            },
            "dispersion": true,
            "colorimetric_standard": "CIE_1931",
            "fast_transmission_gathering": false,
            "ambient_material_uri": "",
            "stop_condition_rays_number": "200000",
            "automatic_save_frequency": 1800
        },
        "name": "Simulation.1",
        "description": "",
        "metadata": {},
        "scene_guid": "d1d733f2-9420-42f9-8b64-f607fda19cec",
        "simulation_path": "Simulation.1",
        "job_type": "CPU"
    }
}

Read project information

[11]:
print(p)
{
    "part_guid": "9c605305-21ab-4619-b863-c983f26572f5",
    "sources": [
        {
            "name": "Surface.1",
            "metadata": {
                "UniqueId": "434edcb8-c676-4884-881e-b9c26e4e239e"
            },
            "source_guid": "ac2e141f-73e6-4389-966a-f97f6d7011da",
            "description": "",
            "source": {
                "name": "Surface.1",
                "surface": {
                    "luminous_flux": {
                        "luminous_value": 683.0
                    },
                    "intensity_guid": "be2a69f8-cf74-490f-a7a5-542e782ed7b9",
                    "exitance_constant": {
                        "geo_paths": [
                            {
                                "geo_path": "Body.1/Face.1",
                                "reverse_normal": true
                            }
                        ]
                    },
                    "spectrum_guid": "b2df0340-c97c-42f5-ab6d-f9fa7cae1e01",
                    "intensity": {
                        "name": "Surface.1.Intensity",
                        "cos": {
                            "N": 1.0,
                            "total_angle": 180.0
                        },
                        "description": "",
                        "metadata": {}
                    },
                    "spectrum": {
                        "name": "Surface.1.Spectrum",
                        "blackbody": {
                            "temperature": 2856.0
                        },
                        "description": "",
                        "metadata": {}
                    }
                },
                "description": "",
                "metadata": {}
            }
        }
    ],
    "sensors": [
        {
            "name": "Irradiance.1",
            "metadata": {
                "UniqueId": "60e158ca-2a75-4cde-9f11-72457066729d"
            },
            "sensor_guid": "568df67f-5119-44f7-a271-9be86a92124b",
            "description": "",
            "result_file_name": "",
            "sensor": {
                "irradiance_sensor_template": {
                    "sensor_type_colorimetric": {
                        "wavelengths_range": {
                            "w_start": 400.0,
                            "w_end": 700.0,
                            "w_sampling": 13
                        }
                    },
                    "illuminance_type_planar": {},
                    "dimensions": {
                        "x_start": -50.0,
                        "x_end": 50.0,
                        "x_sampling": 100,
                        "y_start": -50.0,
                        "y_end": 50.0,
                        "y_sampling": 100
                    },
                    "axis_system": [
                        0.0,
                        0.0,
                        0.0,
                        1.0,
                        0.0,
                        0.0,
                        0.0,
                        1.0,
                        0.0,
                        0.0,
                        0.0,
                        1.0
                    ],
                    "layer_type_none": {},
                    "ray_file_type": "RayFileNone",
                    "integration_direction": []
                },
                "name": "Irradiance.1",
                "description": "",
                "metadata": {}
            }
        }
    ],
    "simulations": [
        {
            "name": "Simulation.1",
            "metadata": {
                "UniqueId": "e7b9cb87-125b-44d6-bc81-ad3426a05b5a"
            },
            "simulation_guid": "3a0d6d50-fac6-4df9-9d26-5c668e97416d",
            "sensor_paths": [
                "Irradiance.1"
            ],
            "source_paths": [
                "Surface.1"
            ],
            "description": "",
            "simulation": {
                "direct_mc_simulation_template": {
                    "geom_distance_tolerance": 0.01,
                    "max_impact": 100,
                    "weight": {
                        "minimum_energy_percentage": 0.005
                    },
                    "dispersion": true,
                    "colorimetric_standard": "CIE_1931",
                    "fast_transmission_gathering": false,
                    "ambient_material_uri": "",
                    "stop_condition_rays_number": "200000",
                    "automatic_save_frequency": 1800
                },
                "name": "Simulation.1",
                "description": "",
                "metadata": {},
                "scene_guid": "d1d733f2-9420-42f9-8b64-f607fda19cec",
                "simulation_path": "Simulation.1",
                "job_type": "CPU"
            }
        },
        {
            "name": "Simulation.2",
            "metadata": {
                "UniqueId": "0b3dca06-11f3-4501-8137-a9faf134b257"
            },
            "simulation_guid": "89e48372-4732-4d92-b797-cbaf7f8e2f36",
            "sensor_paths": [
                "Irradiance.1"
            ],
            "source_paths": [
                "Surface.1"
            ],
            "description": "",
            "simulation": {
                "direct_mc_simulation_template": {
                    "geom_distance_tolerance": 0.01,
                    "max_impact": 200,
                    "colorimetric_standard": "CIE_1964",
                    "ambient_material_uri": "/app/assets/AIR.material",
                    "dispersion": false,
                    "fast_transmission_gathering": false,
                    "stop_condition_rays_number": "200000",
                    "automatic_save_frequency": 1800
                },
                "name": "Simulation.2",
                "description": "",
                "metadata": {},
                "scene_guid": "d1d733f2-9420-42f9-8b64-f607fda19cec",
                "simulation_path": "Simulation.2",
                "job_type": "CPU"
            }
        }
    ],
    "materials": [
        {
            "name": "Material.1",
            "metadata": {
                "UniqueId": "3d1b644d-698e-4b31-aa9e-56ed8cf63711"
            },
            "vop_guid": "d63d0621-953e-4a26-8526-06b6be201233",
            "sop_guids": [
                "1bc04421-e0c1-47e1-9294-982611c2a70d"
            ],
            "geometries": {
                "geo_paths": [
                    "Body.1"
                ]
            },
            "description": "",
            "vop": {
                "name": "Material.1.VOP",
                "opaque": {},
                "description": "",
                "metadata": {}
            },
            "sops": [
                {
                    "name": "Material.1.SOP",
                    "mirror": {
                        "reflectance": 100.0
                    },
                    "description": "",
                    "metadata": {}
                }
            ]
        }
    ],
    "name": "",
    "description": "",
    "metadata": {},
    "scenes": []
}

Update simulation settings#

If you are manipulating a simulation already committed, remember to commit your changes.

If you don’t, you will still only watch what is committed on the server.

[12]:
simulation1.set_ambient_material_file_uri(uri=str(assets_data_path / "AIR.material"))
simulation1.commit()
print(simulation1)
{
    "name": "Simulation.1",
    "metadata": {
        "UniqueId": "e7b9cb87-125b-44d6-bc81-ad3426a05b5a"
    },
    "simulation_guid": "3a0d6d50-fac6-4df9-9d26-5c668e97416d",
    "sensor_paths": [
        "Irradiance.1"
    ],
    "source_paths": [
        "Surface.1"
    ],
    "description": "",
    "simulation": {
        "direct_mc_simulation_template": {
            "geom_distance_tolerance": 0.01,
            "max_impact": 100,
            "weight": {
                "minimum_energy_percentage": 0.005
            },
            "dispersion": true,
            "ambient_material_uri": "/app/assets/AIR.material",
            "colorimetric_standard": "CIE_1931",
            "fast_transmission_gathering": false,
            "stop_condition_rays_number": "200000",
            "automatic_save_frequency": 1800
        },
        "name": "Simulation.1",
        "description": "",
        "metadata": {},
        "scene_guid": "d1d733f2-9420-42f9-8b64-f607fda19cec",
        "simulation_path": "Simulation.1",
        "job_type": "CPU"
    }
}

Reset#

Possibility to reset local values from the one available in the server.

[13]:
simulation1.set_max_impact(1000)  # adjust max impact but no commit
simulation1.reset()  # reset -> this will apply the server value to the local value
simulation1.delete()  # delete (to display the local value with the below print)
print(simulation1)
local: {
    "name": "Simulation.1",
    "sensor_paths": [
        "Irradiance.1"
    ],
    "source_paths": [
        "Surface.1"
    ],
    "description": "",
    "metadata": {},
    "simulation_guid": "",
    "simulation": {
        "direct_mc_simulation_template": {
            "geom_distance_tolerance": 0.01,
            "max_impact": 100,
            "weight": {
                "minimum_energy_percentage": 0.005
            },
            "dispersion": true,
            "ambient_material_uri": "/app/assets/AIR.material",
            "colorimetric_standard": "CIE_1931",
            "fast_transmission_gathering": false,
            "stop_condition_rays_number": "200000",
            "automatic_save_frequency": 1800
        },
        "name": "Simulation.1",
        "description": "",
        "metadata": {},
        "scene_guid": "d1d733f2-9420-42f9-8b64-f607fda19cec",
        "simulation_path": "Simulation.1",
        "job_type": "CPU"
    }
}

Other simulation examples#

Inverse simulation#

[14]:
simulation3 = p.create_simulation(name="Simulation.3", feature_type=SimulationInverse)
simulation3.set_sensor_paths(sensor_paths=["Irradiance.1"]).set_source_paths(
    source_paths=["Surface.1"]
).commit()
print(simulation3)
{
    "name": "Simulation.3",
    "metadata": {
        "UniqueId": "65799362-139f-45a1-bcc6-77021607b436"
    },
    "simulation_guid": "e7d19978-a742-4bbc-9c6b-a15d4694bae3",
    "sensor_paths": [
        "Irradiance.1"
    ],
    "source_paths": [
        "Surface.1"
    ],
    "description": "",
    "simulation": {
        "inverse_mc_simulation_template": {
            "geom_distance_tolerance": 0.01,
            "max_impact": 100,
            "weight": {
                "minimum_energy_percentage": 0.005
            },
            "number_of_gathering_rays_per_source": 1,
            "colorimetric_standard": "CIE_1931",
            "dispersion": false,
            "splitting": false,
            "maximum_gathering_error": 0,
            "maximum_gathering_error_percentage": 0.0,
            "fast_transmission_gathering": false,
            "ambient_material_uri": "",
            "optimized_propagation_none": {
                "stop_condition_passes_number": 5
            },
            "automatic_save_frequency": 1800
        },
        "name": "Simulation.3",
        "description": "",
        "metadata": {},
        "scene_guid": "d1d733f2-9420-42f9-8b64-f607fda19cec",
        "simulation_path": "Simulation.3",
        "job_type": "CPU"
    }
}

Interactive simulation#

[15]:
simulation4 = p.create_simulation(name="Simulation.4", feature_type=SimulationInteractive)
simulation4.set_source_paths(source_paths=["Surface.1"]).commit()
print(simulation4)
{
    "name": "Simulation.4",
    "metadata": {
        "UniqueId": "c0330d56-5f1e-4b19-8c1b-8a52938c23d0"
    },
    "simulation_guid": "52161007-249f-4f60-9d80-041288b6426a",
    "source_paths": [
        "Surface.1"
    ],
    "description": "",
    "sensor_paths": [],
    "simulation": {
        "name": "Simulation.4",
        "interactive_simulation_template": {
            "geom_distance_tolerance": 0.01,
            "max_impact": 100,
            "weight": {
                "minimum_energy_percentage": 0.005
            },
            "colorimetric_standard": "CIE_1931",
            "ambient_material_uri": "",
            "rays_number_per_sources": [],
            "light_expert": false,
            "impact_report": false
        },
        "description": "",
        "metadata": {},
        "scene_guid": "d1d733f2-9420-42f9-8b64-f607fda19cec",
        "simulation_path": "Simulation.4",
        "job_type": "CPU"
    }
}