Download this example
Download this example as a Jupyter Notebook or as a Python script. All assets used in the examples can be downloaded as a ZIP archive.
How to create a project#
This tutorial demonstrates how to create a project.
What is a project?#
A project is a speos simulation container that includes parts, material properties, sensor, sources and simulations.
In this tutorial you will learn how to create a project from scratch or from a pre-defined .speos file.
Prerequisites#
Perform imports#
[1]:
import os
from pathlib import Path
from ansys.speos.core import Project, Speos
from ansys.speos.core.generic.version_checker import server_version_checker
from ansys.speos.core.kernel.client import (
default_docker_channel,
)
from ansys.speos.core.launcher import launch_local_speos_rpc_server
from ansys.speos.core.sensor import SensorIrradiance
from ansys.speos.core.simulation import SimulationDirect
from ansys.speos.core.source import SourceLuminaire, SourceSurface
Define constants#
The constants help ensure consistency and avoid repetition throughout the example.
[2]:
HOSTNAME = "localhost"
GRPC_PORT = 50098 # Be sure the Speos GRPC Server has been started on this port.
USE_DOCKER = True # Set to False if you're running this example locally as a Notebook.
Model Setup#
Load assets#
The assets used to run this example are available in the PySpeos repository on GitHub.
Note: Make sure you have downloaded simulation assets and set
assets_data_pathto point to the assets folder.
[3]:
if USE_DOCKER: # Running on the remote server.
assets_data_path = Path("/app") / "assets"
else:
assets_data_path = Path("/path/to/your/download/assets/directory")
Start/Connect to Speos RPC Server#
This Python client connects to a server where the Speos engine is running as a service. In this example, the server and client are the same machine. the launch_local_speos_rpc_method can be used to start a local instance of the service.
[4]:
if USE_DOCKER:
speos = Speos(channel=default_docker_channel())
else:
speos = launch_local_speos_rpc_server(port=GRPC_PORT)
/home/runner/work/pyspeos/pyspeos/.venv/lib/python3.14/site-packages/ansys/tools/common/cyberchannel.py:201: UserWarning: Starting gRPC client without TLS on localhost:50098. This is INSECURE. Consider using a secure connection.
warn(f"Starting gRPC client without TLS on {target}. This is INSECURE. Consider using a secure connection.")
New empty project#
An empty project can be created by only passing speos rpc server to the Project class.
[5]:
p = Project(speos=speos)
print(p)
{
"name": "",
"description": "",
"metadata": {},
"part_guid": "",
"sub_scene_anchor_axis_system": [],
"sources": [],
"sensors": [],
"simulations": [],
"materials": [],
"scenes": []
}
Create features#
The Project class has a multitude of method to create Speos features. each create methedo takes the name and the Feature type as arguments and returns the created Feature #### Source
[6]:
source1 = p.create_source(name="Source.1", feature_type=SourceLuminaire)
source1.intensity_file_uri = assets_data_path / "IES_C_DETECTOR.ies"
source1.commit()
[6]:
<ansys.speos.core.source.SourceLuminaire at 0x7f3d4579b4d0>
Sensor#
[7]:
sensor1 = p.create_sensor(name="Sensor.1")
sensor1.commit()
[7]:
<ansys.speos.core.sensor.SensorIrradiance at 0x7f3d8c2756a0>
Optical property#
[8]:
opt_prop1 = p.create_optical_property(name="Material.1")
opt_prop1.commit()
[8]:
<ansys.speos.core.opt_prop.OptProp at 0x7f3d8c275d30>
Read Project#
User can read the content of a project via simply printing the project
[9]:
print(p)
{
"sources": [
{
"name": "Source.1",
"metadata": {
"UniqueId": "fa089322-08bd-4287-9a6d-9d870c2e156e"
},
"source_guid": "770c3997-7b12-4294-b103-84e06b6da7a3",
"display_name": "",
"description": "",
"source": {
"name": "Source.1",
"luminaire": {
"flux_from_intensity_file": {},
"intensity_file_uri": "/app/assets/IES_C_DETECTOR.ies",
"spectrum_guid": "aa8e74de-1710-4168-900f-85c9705547f2",
"spectrum": {
"name": "Source.1.Spectrum",
"predefined": {
"incandescent": {}
},
"description": "",
"metadata": {}
},
"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
]
},
"description": "",
"metadata": {}
}
}
],
"sensors": [
{
"name": "Sensor.1",
"metadata": {
"UniqueId": "cbf5f9c7-fc71-4f0d-ae4b-da38f4c43ba5"
},
"sensor_guid": "7a37abda-70ca-4595-a1de-f4e3b1e3cc1c",
"display_name": "",
"description": "",
"result_file_name": "",
"sensor": {
"irradiance_sensor_template": {
"sensor_type_photometric": {},
"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": "Sensor.1",
"description": "",
"metadata": {}
}
}
],
"materials": [
{
"name": "Material.1",
"metadata": {
"UniqueId": "ff5b3763-f4f4-4565-9dba-6fa6dc1aa1c8"
},
"sop_guid": "733da34a-3e60-4545-852e-3d862e9e3c94",
"display_name": "",
"description": "",
"sop_guids": [],
"sop": {
"name": "Material.1.SOP",
"mirror": {
"reflectance": 100.0
},
"description": "",
"metadata": {}
}
}
],
"name": "",
"description": "",
"metadata": {},
"part_guid": "",
"sub_scene_anchor_axis_system": [],
"simulations": [],
"scenes": []
}
Or, user can use the find_key method to read a specific feature:
[10]:
for it in p.find_key(key="monochromatic"):
print(it)
Find a feature inside a project#
Use find method with an exact name#
If no feature is found, an empty list is returned.
[11]:
features = p.find(name="UnexistingName")
print(features)
[]
[12]:
features = p.find(name="Sensor.1")
print(features[0])
{
"name": "Sensor.1",
"metadata": {
"UniqueId": "cbf5f9c7-fc71-4f0d-ae4b-da38f4c43ba5"
},
"sensor_guid": "7a37abda-70ca-4595-a1de-f4e3b1e3cc1c",
"display_name": "",
"description": "",
"result_file_name": "",
"sensor": {
"irradiance_sensor_template": {
"sensor_type_photometric": {},
"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": "Sensor.1",
"description": "",
"metadata": {}
}
}
Use find method with feature type#
Here a wrong type is given: no source is called Sensor.1 in the project
[13]:
features = p.find(name="Sensor.1", feature_type=SourceLuminaire)
print(features)
[]
[14]:
features = p.find(name="Sensor.1", feature_type=SensorIrradiance)
print(features[0])
{
"name": "Sensor.1",
"metadata": {
"UniqueId": "cbf5f9c7-fc71-4f0d-ae4b-da38f4c43ba5"
},
"sensor_guid": "7a37abda-70ca-4595-a1de-f4e3b1e3cc1c",
"display_name": "",
"description": "",
"result_file_name": "",
"sensor": {
"irradiance_sensor_template": {
"sensor_type_photometric": {},
"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": "Sensor.1",
"description": "",
"metadata": {}
}
}
Use find method with approximation name with regex#
find a feature with name starting with Mat
[15]:
features = p.find(name="Mat.*", name_regex=True)
for feat in features:
print(str(type(feat)) + " : name=" + feat._name)
<class 'ansys.speos.core.opt_prop.OptProp'> : name=Material.1
find all features without defining any name
[16]:
features = p.find(name=".*", name_regex=True)
for feat in features:
print(str(type(feat)) + " : name=" + feat._name)
<class 'ansys.speos.core.source.SourceLuminaire'> : name=Source.1
<class 'ansys.speos.core.sensor.SensorIrradiance'> : name=Sensor.1
<class 'ansys.speos.core.opt_prop.OptProp'> : name=Material.1
Delete#
This erases the scene content in server database.
This deletes also each feature of the project
[17]:
p.delete()
print(p)
{
"name": "",
"description": "",
"metadata": {},
"part_guid": "",
"sub_scene_anchor_axis_system": [],
"sources": [],
"sensors": [],
"simulations": [],
"materials": [],
"scenes": []
}
As the features were deleted just above -> this returns an empty vector
[18]:
print(p.find(name="Sensor.1"))
[]
Create project from pre-defined speos project#
Via passing the .speos/.sv5 file path to the Project class.
[19]:
p2 = Project(
speos=speos,
path=str(assets_data_path / "LG_50M_Colorimetric_short.sv5" / "LG_50M_Colorimetric_short.sv5"),
)
print(p2)
{
"name": "LG_50M_Colorimetric_short",
"description": "From Speos file: /app/assets/LG_50M_Colorimetric_short.sv5/LG_50M_Colorimetric_short.sv5",
"part_guid": "e038ce81-360b-4517-b387-2da604833993",
"sources": [
{
"name": "Dom Source 2 (0) in SOURCE2",
"metadata": {
"UniqueId": "b7e9624a-4c6d-4542-a960-c8d655c0cf23"
},
"source_guid": "092bfa1a-7651-4555-a25a-af8aaec7be0a",
"display_name": "",
"description": "",
"source": {
"name": "Dom Source 2 (0) in SOURCE2",
"surface": {
"radiant_flux": {
"radiant_value": 6.590041607465698
},
"intensity_guid": "d7e80f8d-ea4a-4d03-980b-9f5fb85a3a06",
"exitance_constant": {
"geo_paths": [
{
"geo_path": "Solid Body in SOURCE2:2920204960/Face in SOURCE2:222",
"reverse_normal": false
}
]
},
"spectrum_guid": "bbc6b538-ea6f-4878-81a8-3dcbea4d0699",
"intensity": {
"cos": {
"N": 1.0,
"total_angle": 180.0
},
"name": "",
"description": "",
"metadata": {}
},
"spectrum": {
"library": {
"file_uri": "/app/assets/LG_50M_Colorimetric_short.sv5/Red Spectrum.spectrum"
},
"name": "",
"description": "",
"metadata": {}
}
},
"description": "",
"metadata": {}
}
},
{
"name": "Surface Source (0) in SOURCE1",
"metadata": {
"UniqueId": "416f45ce-1553-487c-a2cf-2bac72b6842e"
},
"source_guid": "c6e92d05-c370-4119-95e0-1ca387dff97e",
"display_name": "",
"description": "",
"source": {
"name": "Surface Source (0) in SOURCE1",
"surface": {
"radiant_flux": {
"radiant_value": 9.290411220389682
},
"intensity_guid": "ff1b94cd-9a52-4a66-8dc7-e8af37b41962",
"exitance_constant": {
"geo_paths": [
{
"geo_path": "Solid Body in SOURCE1:2494956811/Face in SOURCE1:187",
"reverse_normal": false
}
]
},
"spectrum_guid": "4f51e88d-74c7-46f1-83f9-463203eb37d0",
"intensity": {
"cos": {
"N": 1.0,
"total_angle": 180.0
},
"name": "",
"description": "",
"metadata": {}
},
"spectrum": {
"library": {
"file_uri": "/app/assets/LG_50M_Colorimetric_short.sv5/Blue Spectrum.spectrum"
},
"name": "",
"description": "",
"metadata": {}
}
},
"description": "",
"metadata": {}
}
}
],
"sensors": [
{
"name": "Dom Irradiance Sensor (0)",
"metadata": {
"UniqueId": "17772a9f-c50c-4887-8494-ef38c736cbac"
},
"sensor_guid": "93215da0-b41f-4886-affc-75960ed8ba9f",
"result_file_name": "ASSEMBLY1.DS (0).Dom Irradiance Sensor (0)",
"display_name": "",
"description": "",
"sensor": {
"irradiance_sensor_template": {
"sensor_type_colorimetric": {
"wavelengths_range": {
"w_start": 400.0,
"w_end": 700.0,
"w_sampling": 25
}
},
"illuminance_type_planar": {},
"dimensions": {
"x_start": -20.0,
"x_end": 20.0,
"x_sampling": 500,
"y_start": -20.0,
"y_end": 20.0,
"y_sampling": 500
},
"axis_system": [
-42.0,
2.0,
5.0,
0.0,
1.0,
0.0,
0.0,
0.0,
-1.0,
-1.0,
0.0,
0.0
],
"layer_type_source": {},
"integration_direction": [
1.0,
-0.0,
-0.0
],
"ray_file_type": "RayFileNone"
},
"name": "Dom Irradiance Sensor (0)",
"description": "",
"metadata": {}
}
}
],
"simulations": [
{
"name": "ASSEMBLY1.DS (0)",
"metadata": {
"UniqueId": "3dca579a-0af2-47fc-b836-65ac400eda43"
},
"simulation_guid": "2c430874-3810-4209-aea3-daa90a92b2b6",
"sensor_paths": [
"Dom Irradiance Sensor (0)"
],
"source_paths": [
"Dom Source 2 (0) in SOURCE2",
"Surface Source (0) in SOURCE1"
],
"geometries": {
"geo_paths": []
},
"display_name": "",
"description": "",
"source_groups": [],
"simulation": {
"direct_mc_simulation_template": {
"geom_distance_tolerance": 0.05,
"max_impact": 100,
"weight": {
"minimum_energy_percentage": 0.005
},
"dispersion": true,
"colorimetric_standard": "CIE_1931",
"fast_transmission_gathering": false,
"ambient_material_uri": ""
},
"name": "ASSEMBLY1.DS (0)",
"metadata": {},
"description": "",
"scene_guid": "6fb1a76b-d0c8-44d7-bcd5-18790566f48c",
"simulation_path": "ASSEMBLY1.DS (0)",
"job_type": "CPU"
}
}
],
"materials": [
{
"name": "Material.1",
"metadata": {
"UniqueId": "6087d7e8-c433-4ad8-92c7-1f398bdc633b"
},
"geometries": {
"geo_paths": [
"Solid Body in GUIDE:1379760262/Face in GUIDE:169"
]
},
"sop_guid": "a3fec451-e32d-4455-bc29-93167f05a2f1",
"display_name": "",
"description": "",
"sop_guids": [],
"sop": {
"mirror": {
"reflectance": 100.0
},
"name": "",
"description": "",
"metadata": {}
}
},
{
"name": "Material.2",
"metadata": {
"UniqueId": "eae9ad0c-efd1-4400-85c2-e5d0cdd64779"
},
"vop_guid": "6c477d70-fe85-4d4c-9db6-0f22458a0775",
"geometries": {
"geo_paths": [
"Solid Body in SOURCE2:2920204960",
"Solid Body in SOURCE1:2494956811"
]
},
"sop_guid": "a3fec451-e32d-4455-bc29-93167f05a2f1",
"display_name": "",
"description": "",
"sop_guids": [],
"vop": {
"opaque": {},
"name": "",
"description": "",
"metadata": {}
},
"sop": {
"mirror": {
"reflectance": 100.0
},
"name": "",
"description": "",
"metadata": {}
}
},
{
"name": "Material.3",
"metadata": {
"UniqueId": "71056f7b-e0db-4181-b0f7-acff711378f1"
},
"vop_guid": "8a17b17a-8013-4af4-a90b-0f27edf85580",
"geometries": {
"geo_paths": [
"Solid Body in GUIDE:1379760262"
]
},
"sop_guid": "c4612b7d-34cd-4837-a653-916614041cca",
"display_name": "",
"description": "",
"sop_guids": [],
"vop": {
"optic": {
"index": 1.4,
"constringence": 60.0,
"absorption": 0.0
},
"name": "",
"description": "",
"metadata": {}
},
"sop": {
"optical_polished": {},
"name": "",
"description": "",
"metadata": {}
}
},
{
"name": "Material.4",
"metadata": {
"UniqueId": "2213dbd7-911b-48e4-9378-f721d5a7a9b5"
},
"vop_guid": "84019fde-a6ec-4817-a8c3-811a818e6b56",
"display_name": "",
"description": "",
"sop_guids": [],
"vop": {
"optic": {
"index": 1.0,
"absorption": 0.0
},
"name": "",
"description": "",
"metadata": {}
}
}
],
"metadata": {},
"sub_scene_anchor_axis_system": [],
"scenes": []
}
Preview the part information#
User can check the project part using preview method.
[20]:
p2.preview()
use find_key method to find specific information
[21]:
for it in p2.find_key(key="surface"):
print(it)
(".sources[.name='Dom Source 2 (0) in SOURCE2'].source.surface", {'radiant_flux': {'radiant_value': 6.590041607465698}, 'intensity_guid': 'd7e80f8d-ea4a-4d03-980b-9f5fb85a3a06', 'exitance_constant': {'geo_paths': [{'geo_path': 'Solid Body in SOURCE2:2920204960/Face in SOURCE2:222', 'reverse_normal': False}]}, 'spectrum_guid': 'bbc6b538-ea6f-4878-81a8-3dcbea4d0699', 'intensity': {'cos': {'N': 1.0, 'total_angle': 180.0}, 'name': '', 'description': '', 'metadata': {}}, 'spectrum': {'library': {'file_uri': '/app/assets/LG_50M_Colorimetric_short.sv5/Red Spectrum.spectrum'}, 'name': '', 'description': '', 'metadata': {}}})
(".sources[.name='Surface Source (0) in SOURCE1'].source.surface", {'radiant_flux': {'radiant_value': 9.290411220389682}, 'intensity_guid': 'ff1b94cd-9a52-4a66-8dc7-e8af37b41962', 'exitance_constant': {'geo_paths': [{'geo_path': 'Solid Body in SOURCE1:2494956811/Face in SOURCE1:187', 'reverse_normal': False}]}, 'spectrum_guid': '4f51e88d-74c7-46f1-83f9-463203eb37d0', 'intensity': {'cos': {'N': 1.0, 'total_angle': 180.0}, 'name': '', 'description': '', 'metadata': {}}, 'spectrum': {'library': {'file_uri': '/app/assets/LG_50M_Colorimetric_short.sv5/Blue Spectrum.spectrum'}, 'name': '', 'description': '', 'metadata': {}}})
Use find method to retrieve feature:
e.g. surface source
[22]:
features = p2.find(name=".*", name_regex=True, feature_type=SourceSurface)
print(features)
for feat in features:
print(str(type(feat)) + " : name=" + feat._name)
src = features[1]
[<ansys.speos.core.source.SourceSurface object at 0x7f3d8c277770>, <ansys.speos.core.source.SourceSurface object at 0x7f3d44ffe0d0>]
<class 'ansys.speos.core.source.SourceSurface'> : name=Dom Source 2 (0) in SOURCE2
<class 'ansys.speos.core.source.SourceSurface'> : name=Surface Source (0) in SOURCE1
modify the surface source, e.g. surface source wavelength:
[23]:
src.spectrum.set_monochromatic().wavelength = 550
src.commit()
[23]:
<ansys.speos.core.source.SourceSurface at 0x7f3d44ffe0d0>
Retrieve a simulation feature:
[24]:
features = p2.find(name=".*", name_regex=True, feature_type=SimulationDirect)
sim_feat = features[0]
print(sim_feat)
{
"name": "ASSEMBLY1.DS (0)",
"metadata": {
"UniqueId": "3dca579a-0af2-47fc-b836-65ac400eda43"
},
"simulation_guid": "2c430874-3810-4209-aea3-daa90a92b2b6",
"sensor_paths": [
"Dom Irradiance Sensor (0)"
],
"source_paths": [
"Dom Source 2 (0) in SOURCE2",
"Surface Source (0) in SOURCE1"
],
"geometries": {
"geo_paths": []
},
"display_name": "",
"description": "",
"source_groups": [],
"simulation": {
"direct_mc_simulation_template": {
"geom_distance_tolerance": 0.05,
"max_impact": 100,
"weight": {
"minimum_energy_percentage": 0.005
},
"dispersion": true,
"colorimetric_standard": "CIE_1931",
"fast_transmission_gathering": false,
"ambient_material_uri": ""
},
"name": "ASSEMBLY1.DS (0)",
"metadata": {},
"description": "",
"scene_guid": "6fb1a76b-d0c8-44d7-bcd5-18790566f48c",
"simulation_path": "ASSEMBLY1.DS (0)",
"job_type": "CPU"
}
}
[25]:
sim_feat.compute_CPU()
[25]:
[upload_response {
info {
uri: "ed419ca3-9c1e-4f2c-bc35-aaf34196705d"
file_name: "ASSEMBLY1.DS (0).Dom Irradiance Sensor (0).xmp"
file_size: 1191128
}
}
, upload_response {
info {
uri: "3c460e7a-3570-418d-8cf2-8fd820903301"
file_name: "ASSEMBLY1.DS (0).html"
file_size: 206373
}
}
]
Preview simulation result
[26]:
# Method available only on Windows OS or with Speos 2026 R1.2 or higher,
# which supports opening XMP results as images regardless of the OS.
if os.name == "nt" or server_version_checker.is_version_supported(2026, 1, 2):
from ansys.speos.core.workflow.open_result import open_result_image
open_result_image(
simulation_feature=sim_feat,
result_name="ASSEMBLY1.DS (0).Dom Irradiance Sensor (0).xmp",
)
[27]:
speos.close()
[27]:
True
Download this example
Download this example as a Jupyter Notebook or as a Python script. All assets used in the examples can be downloaded as a ZIP archive.