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_path to 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": [],
    "textures_3d": []
}

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

Sensor#

[7]:
sensor1 = p.create_sensor(name="Sensor.1")
sensor1.commit()
[7]:
<ansys.speos.core.sensor.SensorIrradiance at 0x7f6b9f5cb230>

Optical property#

[8]:
opt_prop1 = p.create_optical_property(name="Material.1")
opt_prop1.commit()
[8]:
<ansys.speos.core.opt_prop.OptProp at 0x7f6b9f5cb8c0>

Read Project#

User can read the content of a project via simply printing the project

[9]:
print(p)
{
    "sources": [
        {
            "name": "Source.1",
            "metadata": {
                "UniqueId": "9245fe97-d2f3-44e4-99da-ee2dfcc894f7"
            },
            "source_guid": "c884585b-855d-44e4-b8f9-981beed68126",
            "display_name": "",
            "description": "",
            "source": {
                "name": "Source.1",
                "luminaire": {
                    "flux_from_intensity_file": {},
                    "intensity_file_uri": "/app/assets/IES_C_DETECTOR.ies",
                    "spectrum_guid": "cd4acb3c-302f-4afc-8379-a7564e25e1c2",
                    "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": "88efe0e8-8773-4c3d-9ef9-9f344bcb2c40"
            },
            "sensor_guid": "def17b67-ac95-4819-9a2e-19a6bdd6a120",
            "display_name": "",
            "description": "",
            "result_file_name": "",
            "sensor": {
                "name": "Sensor.1",
                "irradiance": {
                    "mode_photometric": {},
                    "integration_type": "INTEGRATION_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": []
                },
                "description": "",
                "metadata": {}
            }
        }
    ],
    "materials": [
        {
            "name": "Material.1",
            "metadata": {
                "UniqueId": "48c5744e-a6f3-4c64-9028-082796d8af6e"
            },
            "sop_guid": "d2e031a1-222c-43c2-a24d-ebca4aa8e7a8",
            "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": [],
    "textures_3d": []
}

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": "88efe0e8-8773-4c3d-9ef9-9f344bcb2c40"
    },
    "sensor_guid": "def17b67-ac95-4819-9a2e-19a6bdd6a120",
    "display_name": "",
    "description": "",
    "result_file_name": "",
    "sensor": {
        "name": "Sensor.1",
        "irradiance": {
            "mode_photometric": {},
            "integration_type": "INTEGRATION_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": []
        },
        "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": "88efe0e8-8773-4c3d-9ef9-9f344bcb2c40"
    },
    "sensor_guid": "def17b67-ac95-4819-9a2e-19a6bdd6a120",
    "display_name": "",
    "description": "",
    "result_file_name": "",
    "sensor": {
        "name": "Sensor.1",
        "irradiance": {
            "mode_photometric": {},
            "integration_type": "INTEGRATION_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": []
        },
        "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": [],
    "textures_3d": []
}

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": "5c0022d4-91d4-4952-9698-306ae779f2d4",
    "sources": [
        {
            "name": "Dom Source 2 (0) in SOURCE2",
            "metadata": {
                "UniqueId": "489ad7cb-ad07-4f18-ad31-cb53df3a9e23"
            },
            "source_guid": "ff88f72c-fd07-41e6-a80f-a4e158775434",
            "display_name": "",
            "description": "",
            "source": {
                "name": "Dom Source 2 (0) in SOURCE2",
                "surface": {
                    "radiant_flux": {
                        "radiant_value": 6.590041607465698
                    },
                    "intensity_guid": "48778680-c003-493a-adc3-1383dca94f42",
                    "exitance_constant": {
                        "geo_paths": [
                            {
                                "geo_path": "Solid Body in SOURCE2:2920204960/Face in SOURCE2:222",
                                "reverse_normal": false
                            }
                        ]
                    },
                    "spectrum_guid": "eed87596-21ce-4295-82c2-4d417e241684",
                    "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": "a679f95d-b05b-4b14-92ee-9a2e82697227"
            },
            "source_guid": "c92e8cbc-810e-4fe0-9600-5645aedb987f",
            "display_name": "",
            "description": "",
            "source": {
                "name": "Surface Source (0) in SOURCE1",
                "surface": {
                    "radiant_flux": {
                        "radiant_value": 9.290411220389682
                    },
                    "intensity_guid": "75582ced-cd01-4d02-a042-fa80e43ab6f1",
                    "exitance_constant": {
                        "geo_paths": [
                            {
                                "geo_path": "Solid Body in SOURCE1:2494956811/Face in SOURCE1:187",
                                "reverse_normal": false
                            }
                        ]
                    },
                    "spectrum_guid": "8d8152f2-e53d-43f5-bce3-224c19fe2237",
                    "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": "6866ac19-671c-4992-956b-662e640b6c63"
            },
            "sensor_guid": "7d37d83c-f579-4fd6-a695-7f80ea46cf18",
            "result_file_name": "ASSEMBLY1.DS (0).Dom Irradiance Sensor (0)",
            "display_name": "",
            "description": "",
            "sensor": {
                "name": "Dom Irradiance Sensor (0)",
                "irradiance": {
                    "mode_colorimetric": {
                        "wavelengths_range": {
                            "w_start": 400.0,
                            "w_end": 700.0,
                            "w_sampling": 25
                        }
                    },
                    "integration_type": "INTEGRATION_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"
                },
                "description": "",
                "metadata": {}
            }
        }
    ],
    "simulations": [
        {
            "name": "ASSEMBLY1.DS (0)",
            "metadata": {
                "UniqueId": "20ee7878-101b-4246-bbdc-ade84640abc3"
            },
            "simulation_guid": "ba5ef39d-92ee-419f-b4d8-55f17ccaaf16",
            "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": "",
                    "stop_condition_rays_number": "500000",
                    "automatic_save_frequency": 60
                },
                "name": "ASSEMBLY1.DS (0)",
                "metadata": {},
                "description": "",
                "scene_guid": "1eb8a4ec-2dfe-420e-b66f-7d3cfa93ccb3",
                "simulation_path": "ASSEMBLY1.DS (0)",
                "job_type": "CPU"
            }
        }
    ],
    "materials": [
        {
            "name": "Material.1",
            "metadata": {
                "UniqueId": "782e6e38-e62b-4409-a68c-470c7b39ed14"
            },
            "geometries": {
                "geo_paths": [
                    "Solid Body in GUIDE:1379760262/Face in GUIDE:169"
                ]
            },
            "sop_guid": "ce38fe8a-953d-45c6-b03c-420ca8dbc7f7",
            "display_name": "",
            "description": "",
            "sop_guids": [],
            "sop": {
                "mirror": {
                    "reflectance": 100.0
                },
                "name": "",
                "description": "",
                "metadata": {}
            }
        },
        {
            "name": "Material.2",
            "metadata": {
                "UniqueId": "fb57baf1-2be6-4366-983a-935671dc9ba6"
            },
            "vop_guid": "fa5b3b5e-0bc2-46b2-b562-67242af3e3b2",
            "geometries": {
                "geo_paths": [
                    "Solid Body in GUIDE:1379760262"
                ]
            },
            "sop_guid": "d9a8a590-1dd7-4588-9b49-d6432ac968b2",
            "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.3",
            "metadata": {
                "UniqueId": "217b62cd-8bc2-41c5-8e8b-1ec44d3fa3a8"
            },
            "vop_guid": "f46258e9-3fce-4fcd-b28a-5cd162edcdaf",
            "geometries": {
                "geo_paths": [
                    "Solid Body in SOURCE2:2920204960",
                    "Solid Body in SOURCE1:2494956811"
                ]
            },
            "sop_guid": "ce38fe8a-953d-45c6-b03c-420ca8dbc7f7",
            "display_name": "",
            "description": "",
            "sop_guids": [],
            "vop": {
                "opaque": {},
                "name": "",
                "description": "",
                "metadata": {}
            },
            "sop": {
                "mirror": {
                    "reflectance": 100.0
                },
                "name": "",
                "description": "",
                "metadata": {}
            }
        }
    ],
    "fast_transmission_gathering": {
        "geometries": {
            "geo_paths": [
                "Solid Body in SOURCE2:2920204960",
                "Solid Body in SOURCE1:2494956811",
                "Solid Body in GUIDE:1379760262"
            ]
        }
    },
    "metadata": {},
    "sub_scene_anchor_axis_system": [],
    "scenes": [],
    "textures_3d": []
}

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': '48778680-c003-493a-adc3-1383dca94f42', 'exitance_constant': {'geo_paths': [{'geo_path': 'Solid Body in SOURCE2:2920204960/Face in SOURCE2:222', 'reverse_normal': False}]}, 'spectrum_guid': 'eed87596-21ce-4295-82c2-4d417e241684', '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': '75582ced-cd01-4d02-a042-fa80e43ab6f1', 'exitance_constant': {'geo_paths': [{'geo_path': 'Solid Body in SOURCE1:2494956811/Face in SOURCE1:187', 'reverse_normal': False}]}, 'spectrum_guid': '8d8152f2-e53d-43f5-bce3-224c19fe2237', '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 0x7f6b9cb39a90>, <ansys.speos.core.source.SourceSurface object at 0x7f6b9cb582d0>]
<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 0x7f6b9cb582d0>

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": "20ee7878-101b-4246-bbdc-ade84640abc3"
    },
    "simulation_guid": "ba5ef39d-92ee-419f-b4d8-55f17ccaaf16",
    "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": "",
            "stop_condition_rays_number": "500000",
            "automatic_save_frequency": 60
        },
        "name": "ASSEMBLY1.DS (0)",
        "metadata": {},
        "description": "",
        "scene_guid": "1eb8a4ec-2dfe-420e-b66f-7d3cfa93ccb3",
        "simulation_path": "ASSEMBLY1.DS (0)",
        "job_type": "CPU"
    }
}
[25]:
sim_feat.compute_CPU()
[25]:
[upload_response {
  info {
    uri: "34be6a7c-08ad-472e-b4ed-d79e109053f7"
    file_name: "ASSEMBLY1.DS (0).Dom Irradiance Sensor (0).xmp"
    file_size: 1191537
  }
}
, upload_response {
  info {
    uri: "acf91e44-0953-46a3-989d-691eee16c956"
    file_name: "ASSEMBLY1.DS (0).html"
    file_size: 205824
  }
}
]

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",
    )
../../_images/examples_core_project_48_0.png
[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.