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.
Prism example#
This tutorial demonstrates how to open an existing Speos file, run the simulation and open the result. After that it explains how to edit the File and adjust Parameters of the sensor.
Prerequisites#
Perform imports#
[1]:
import os
from pathlib import Path
from ansys.speos.core import Body, 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 Sensor3DIrradiance, SensorIrradiance
from ansys.speos.core.simulation import SimulationDirect
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.")
Create project#
Load a project from .speos file.
[5]:
p = Project(speos=speos, path=str(assets_data_path / "Prism.speos" / "Prism.speos"))
print(p)
{
"name": "Prism",
"description": "From Speos file: /app/assets/Prism.speos/Prism.speos",
"part_guid": "1fc9681e-84a6-4fd7-8cf2-262423e8b15b",
"sources": [
{
"name": "Surface.1:7758",
"metadata": {
"UniqueId": "4c431c6f-2365-4511-b815-7ac2240c1805"
},
"source_guid": "8aaca11d-874b-4e36-8195-d65392e62daa",
"display_name": "",
"description": "",
"source": {
"name": "Surface.1:7758",
"surface": {
"radiant_flux": {
"radiant_value": 8.346636625511586
},
"intensity_guid": "1a8808a0-02dd-4c99-83c5-c05d26d0d62d",
"exitance_constant": {
"geo_paths": [
{
"geo_path": "SourceBody:1801986974/face.1:544289899",
"reverse_normal": false
}
]
},
"spectrum_guid": "1428deef-8008-4b8a-a7fe-b107b0ce2e45",
"intensity": {
"cos": {
"N": 1.0,
"total_angle": 0.1
},
"name": "",
"description": "",
"metadata": {}
},
"spectrum": {
"blackbody": {
"temperature": 5000.0
},
"name": "",
"description": "",
"metadata": {}
}
},
"description": "",
"metadata": {}
}
}
],
"sensors": [
{
"name": "Irradiance.1:564",
"metadata": {
"UniqueId": "5bc79c72-dc20-4501-996f-b914f98a6f88"
},
"sensor_guid": "83844f39-c48e-4bca-957f-8635a037cb75",
"result_file_name": "Prism.Irradiance.1",
"display_name": "",
"description": "",
"sensor": {
"irradiance_sensor_template": {
"sensor_type_spectral": {
"wavelengths_range": {
"w_start": 380.0,
"w_end": 780.0,
"w_sampling": 41
}
},
"illuminance_type_planar": {},
"dimensions": {
"x_start": -20.0,
"x_end": 20.0,
"x_sampling": 400,
"y_start": -5.0,
"y_end": 5.0,
"y_sampling": 100
},
"axis_system": [
921.3551052231927,
0.0,
388.72197015239516,
-0.3887219701523952,
-0.0,
0.9213551052231927,
0.0,
1.0000000000000002,
0.0,
-0.9213551052231927,
0.0,
-0.3887219701523952
],
"layer_type_none": {},
"ray_file_type": "RayFileNone",
"integration_direction": []
},
"name": "Irradiance.1:564",
"description": "",
"metadata": {}
}
}
],
"simulations": [
{
"name": "Prism",
"metadata": {
"UniqueId": "ca2211d1-b900-47e3-8ccc-c3317c05b4b3"
},
"simulation_guid": "d1df5596-d096-4589-91c3-9beda8c68224",
"sensor_paths": [
"Irradiance.1:564"
],
"source_paths": [
"Surface.1:7758"
],
"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,
"texture": {
"texture_normalization": "TEXTURE_NORMALIZATION_NONE",
"normal_map": true
},
"colorimetric_standard": "CIE_1931",
"fast_transmission_gathering": false,
"ambient_material_uri": ""
},
"name": "Prism",
"metadata": {},
"description": "",
"scene_guid": "0269d869-27ac-4717-b0c5-f6d548406d16",
"simulation_path": "Prism",
"job_type": "CPU"
}
}
],
"materials": [
{
"name": "Material.1",
"metadata": {
"UniqueId": "dd39cbe2-7ec6-4631-8323-0b131a012e06"
},
"geometries": {
"geo_paths": [
"SourceBody:1801986974/face.1:544289899",
"SourceBody:1801986974/face.1:2282175023",
"SourceBody:1801986974/face.1:2503270562",
"SourceBody:1801986974/face.1:2272456582",
"SourceBody:1801986974/face.1:1596341914",
"SourceBody:1801986974/face.1:387288686"
]
},
"sop_guid": "e37cd4af-cbc7-46c4-9a98-30a028378195",
"display_name": "",
"description": "",
"sop_guids": [],
"sop": {
"mirror": {
"reflectance": 0.0
},
"name": "",
"description": "",
"metadata": {}
}
},
{
"name": "Material.2",
"metadata": {
"UniqueId": "16960e2f-bab0-4611-bf6d-28de2998f3e2"
},
"vop_guid": "6d17e17b-38fc-44ef-80e6-556a9f17ef54",
"geometries": {
"geo_paths": [
"PrismBody:1130610277"
]
},
"sop_guid": "831f3e98-c505-477a-9f34-03bd58c3888d",
"display_name": "",
"description": "",
"sop_guids": [],
"vop": {
"optic": {
"index": 1.5,
"absorption": 0.001,
"constringence": 60.0
},
"name": "",
"description": "",
"metadata": {}
},
"sop": {
"optical_polished": {},
"name": "",
"description": "",
"metadata": {}
}
},
{
"name": "Material.3",
"metadata": {
"UniqueId": "e18f1716-b5ad-4e7d-8a0c-64812a23f0c7"
},
"geometries": {
"geo_paths": [
"PrismBody:1130610277/face.1:242396665"
]
},
"sop_guid": "6c171a29-d11b-418e-a4d7-d6c10eaad4bf",
"display_name": "",
"description": "",
"sop_guids": [],
"sop": {
"library": {
"sop_file_uri": "/app/assets/Prism.speos/transparent_ad06-07cb-a92e-7815..scattering"
},
"name": "",
"description": "",
"metadata": {}
}
},
{
"name": "Material.4",
"metadata": {
"UniqueId": "300069b4-fabe-4a33-816e-1b44d5b68434"
},
"vop_guid": "095f6fdd-d345-4f65-aee7-ed67638fc9ee",
"display_name": "",
"description": "",
"sop_guids": [],
"vop": {
"optic": {
"index": 1.0,
"absorption": 0.0
},
"name": "",
"description": "",
"metadata": {}
}
}
],
"metadata": {},
"sub_scene_anchor_axis_system": [],
"scenes": []
}
Preview#
This preview method allows you to preview the content of the Speos solver file.
[6]:
p.preview()
/home/runner/work/pyspeos/pyspeos/.venv/lib/python3.14/site-packages/ansys/tools/visualization_interface/backends/pyvista/pyvista_interface.py:479: UserWarning: Failed to use notebook backend "html": Please install `ipywidgets`.
Falling back to a static output.
Available backends: "static", "none"
Install trame for interactive backends: pip install "pyvista[jupyter]"
self.scene.show(jupyter_backend=jupyter_backend, **kwargs)
Retrieve the simulation feature and open result#
Run the simulation
[7]:
sim_features = p.find(name="Prism", feature_type=SimulationDirect)
sim = sim_features[0]
sim.compute_CPU()
[7]:
[upload_response {
info {
uri: "f87df17f-51dc-44fb-adb2-88b55b31b14c"
file_name: "Prism.Irradiance.1.xmp"
file_size: 1578849
}
}
, upload_response {
info {
uri: "e01f47c4-28f9-4ff5-98b3-596b620651a6"
file_name: "Prism.html"
file_size: 88254
}
}
]
Use the open_result_image method to review the result
[8]:
# 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, result_name="Prism.Irradiance.1.xmp")
Work with sensor#
Retrieve the sensor feature.
Modify the sensor setting, e.g. set the spectral type, etc.
[9]:
irr_features = p.find(name=".*", name_regex=True, feature_type=SensorIrradiance)
irr = irr_features[0]
wl = irr.set_type_spectral().set_wavelengths_range()
wl.start = 500
wl.end = 600
wl.sampling = 11
irr.commit()
[9]:
<ansys.speos.core.sensor.SensorIrradiance at 0x7f1c961012b0>
Create and add a new sensor, e.g. 3d irradiance sensor
[10]:
body = p.find(name="PrismBody", name_regex=True, feature_type=Body)[0]
sensor_3d = p.create_sensor(name="3d_irradiance", feature_type=Sensor3DIrradiance)
sensor_3d.geometries = [body.geo_path]
sensor_3d.commit()
sim.sensor_paths == ["Irradiance.1:564", "3d_irradiance"]
sim.commit()
p.preview()
Re-run the simulation with new sensor definition.#
[11]:
sim.compute_CPU()
# 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):
open_result_image(simulation_feature=sim, result_name="Prism.Irradiance.1.xmp")
[12]:
speos.close()
[12]:
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.