How to create an optical property#
This tutorial demonstrates how to create an optical property.
What is an optical property?#
An optical property (also named material), gathers two notions: the surface optical property (SOP) and the volume optical property (VOP).
The property is then applied to a geometry (like bodies, faces).
Prerequisites#
Perform imports#
[1]:
from pathlib import Path
from ansys.speos.core import Project, Speos, launcher
Define constants#
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.
Define helper functions#
[3]:
def create_helper_geometries(project: Project):
"""Create bodies and faces."""
def create_face(body):
face = (
body.create_face(name="TheFaceF")
.set_vertices([0, 0, 0, 1, 0, 0, 0, 1, 0])
.set_facets([0, 1, 2])
.set_normals([0, 0, 1, 0, 0, 1, 0, 0, 1])
.commit()
)
return face
data = {"bodies": [], "faces": []}
root_part = project.create_root_part().commit()
data["bodies"].append(root_part.create_body(name="TheBodyB").commit())
data["bodies"].append(root_part.create_body(name="TheBodyC").commit())
data["bodies"].append(root_part.create_body(name="TheBodyD").commit())
data["bodies"].append(root_part.create_body(name="TheBodyE").commit())
for b in data["bodies"]:
data["faces"].append(create_face(b))
return data
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.
[4]:
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")
Connect to the 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.
[5]:
if USE_DOCKER:
speos = Speos(host=HOSTNAME, port=GRPC_PORT)
else:
speos = launcher.launch_local_speos_rpc_server(port=GRPC_PORT)
Create a new project#
The only way to create an optical property using the core layer, is to create it from a project. The Project class is instantiated by passing a Speos instance
[6]:
p = Project(speos=speos)
print(p)
data = create_helper_geometries(p)
bodies = data["bodies"]
faces = data["faces"]
{
"name": "",
"description": "",
"metadata": {},
"part_guid": "",
"sources": [],
"sensors": [],
"simulations": [],
"materials": [],
"scenes": []
}
Create VOP (volume optical property)#
Create locally. The mention “local: “ is added when printing the optical property.
[7]:
op1 = p.create_optical_property(name="Material.1")
op1.set_surface_mirror(reflectance=80) # SOP : mirror
op1.set_volume_opaque() # VOP : opaque
# This optical property will be applied to two bodies named : "TheBodyB" and "TheBodyC".
op1.set_geometries(
geometries=[
bodies[0],
bodies[1],
]
)
print(op1)
local: {
"name": "Material.1",
"geometries": {
"geo_paths": [
"TheBodyB",
"TheBodyC"
]
},
"description": "",
"metadata": {},
"sop_guids": [],
"vop": {
"name": "Material.1.VOP",
"opaque": {},
"description": "",
"metadata": {}
},
"sops": [
{
"name": "Material.1.SOP",
"mirror": {
"reflectance": 80.0
},
"description": "",
"metadata": {}
}
]
}
Push it to the server.#
Now that it is committed to the server, the mention “local: “ is no more present when printing the optical property.
[8]:
op1.commit()
print(op1)
{
"name": "Material.1",
"metadata": {
"UniqueId": "0638552d-8d1f-4cc6-b540-e8f2eb6429ab"
},
"vop_guid": "e4b8f261-285f-49d5-aae8-3f8709b4a036",
"sop_guids": [
"4333ff7c-a423-4920-85a3-1c29fb589f88"
],
"geometries": {
"geo_paths": [
"TheBodyB",
"TheBodyC"
]
},
"description": "",
"vop": {
"name": "Material.1.VOP",
"opaque": {},
"description": "",
"metadata": {}
},
"sops": [
{
"name": "Material.1.SOP",
"mirror": {
"reflectance": 80.0
},
"description": "",
"metadata": {}
}
]
}
Another example.#
Setting several more characteristics.
[9]:
op2 = p.create_optical_property(name="Material.2")
op2.set_surface_opticalpolished() # SOP : optical polished
op2.set_volume_library(
path=str(assets_data_path / "AIR.material")
) # VOP : selected library via a file .material
# This optical property will be applied to two bodies named : "TheBodyD" and "TheBodyE".
op2.set_geometries(
geometries=[
bodies[2],
bodies[3],
]
)
op2.commit()
print(op2)
{
"name": "Material.2",
"metadata": {
"UniqueId": "aaabe4a1-ea84-4bf7-b18a-eb30c8a4df70"
},
"vop_guid": "5022d46f-d359-4fa6-89aa-255519444710",
"sop_guids": [
"b127dc7d-8fc0-4f8e-b4a2-07c52fce2a18"
],
"geometries": {
"geo_paths": [
"TheBodyD",
"TheBodyE"
]
},
"description": "",
"vop": {
"name": "Material.2.VOP",
"library": {
"material_file_uri": "/app/assets/AIR.material"
},
"description": "",
"metadata": {}
},
"sops": [
{
"name": "Material.2.SOP",
"optical_polished": {},
"description": "",
"metadata": {}
}
]
}
Create FOP (face optical property)#
Sometimes it is needed to create property but only for surface.
In this case, no call for set_volume_xxx function is needed, and we will select a face for the geometries.
[10]:
op3 = p.create_optical_property(name="Material.FOP")
op3.set_surface_mirror(reflectance=90) # SOP : mirror
# This optical property will be applied a face from TheBodyD named : "TheFaceF".
op3.set_geometries(geometries=[faces[2]])
op3.commit()
print(op3)
{
"name": "Material.FOP",
"metadata": {
"UniqueId": "533c0723-222e-45a0-a37b-19d938a89cd9"
},
"sop_guids": [
"c4f11ced-fb0b-4024-9863-c77e9fa056ee"
],
"geometries": {
"geo_paths": [
"TheBodyD/TheFaceF"
]
},
"description": "",
"sops": [
{
"name": "Material.FOP.SOP",
"mirror": {
"reflectance": 90.0
},
"description": "",
"metadata": {}
}
]
}
Default values#
Some default values are available when applicable in every methods and class.
[11]:
op4 = p.create_optical_property(name="Material.3").commit()
print(op4)
{
"name": "Material.3",
"metadata": {
"UniqueId": "69467658-301d-43fa-8ab3-b6c5023b1c56"
},
"sop_guids": [
"634ca58f-5e9e-437b-9c97-6e094ee76371"
],
"description": "",
"sops": [
{
"name": "Material.3.SOP",
"mirror": {
"reflectance": 100.0
},
"description": "",
"metadata": {}
}
]
}
Read#
Material Instance Information#
A mention “local: “ is added if it is not yet committed to the server.
[12]:
print(op1)
{
"name": "Material.1",
"metadata": {
"UniqueId": "0638552d-8d1f-4cc6-b540-e8f2eb6429ab"
},
"vop_guid": "e4b8f261-285f-49d5-aae8-3f8709b4a036",
"sop_guids": [
"4333ff7c-a423-4920-85a3-1c29fb589f88"
],
"geometries": {
"geo_paths": [
"TheBodyB",
"TheBodyC"
]
},
"description": "",
"vop": {
"name": "Material.1.VOP",
"opaque": {},
"description": "",
"metadata": {}
},
"sops": [
{
"name": "Material.1.SOP",
"mirror": {
"reflectance": 80.0
},
"description": "",
"metadata": {}
}
]
}
The get methods allows you to get some properties of your feature
[13]:
print("op1 name: {}".format(op1.get(key="name")))
print("geometries linked to op1: {}".format(op1.get(key="geo_paths")))
print("op1 surface optical properties info: {}".format(op1.get(key="sops")))
print("op1 volume optical property info: {}".format(op1.get(key="vop")))
# user can use get with vop type as key word to check volume property type
print(
"op1 {} opaque type volume optical property".format(
"is" if op1.get(key="opaque") is not None else "is not"
)
)
print(op2)
print("op2 name: {}".format(op2.get(key="name")))
print(
"op2 {} optical polished type surface property".format(
("is" if "optical_polished" in op2.get(key="sops")[0] else "is not")
)
)
# an alternative way to check the type of optical property
print(
"op2 {} library type volume optical property".format(
"is" if "library" in op2.get(key="vop") is not None else "is not"
)
)
print(op3)
print("op3 name: {}".format(op3.get(key="name")))
print("op3 has reflectance value of {}".format(op3.get(key="sops")[0]["mirror"]["reflectance"]))
op1 name: Material.1
geometries linked to op1: ['TheBodyB', 'TheBodyC']
op1 surface optical properties info: [{'name': 'Material.1.SOP', 'mirror': {'reflectance': 80.0}, 'description': '', 'metadata': {}}]
op1 volume optical property info: {'name': 'Material.1.VOP', 'opaque': {}, 'description': '', 'metadata': {}}
op1 is opaque type volume optical property
{
"name": "Material.2",
"metadata": {
"UniqueId": "aaabe4a1-ea84-4bf7-b18a-eb30c8a4df70"
},
"vop_guid": "5022d46f-d359-4fa6-89aa-255519444710",
"sop_guids": [
"b127dc7d-8fc0-4f8e-b4a2-07c52fce2a18"
],
"geometries": {
"geo_paths": [
"TheBodyD",
"TheBodyE"
]
},
"description": "",
"vop": {
"name": "Material.2.VOP",
"library": {
"material_file_uri": "/app/assets/AIR.material"
},
"description": "",
"metadata": {}
},
"sops": [
{
"name": "Material.2.SOP",
"optical_polished": {},
"description": "",
"metadata": {}
}
]
}
op2 name: Material.2
op2 is optical polished type surface property
op2 is library type volume optical property
{
"name": "Material.FOP",
"metadata": {
"UniqueId": "533c0723-222e-45a0-a37b-19d938a89cd9"
},
"sop_guids": [
"c4f11ced-fb0b-4024-9863-c77e9fa056ee"
],
"geometries": {
"geo_paths": [
"TheBodyD/TheFaceF"
]
},
"description": "",
"sops": [
{
"name": "Material.FOP.SOP",
"mirror": {
"reflectance": 90.0
},
"description": "",
"metadata": {}
}
]
}
op3 name: Material.FOP
op3 has reflectance value of 90.0
Project Information#
Committed feature information will appear inside a project information.
[14]:
print(p)
{
"part_guid": "d80ec229-0c9d-4697-8ae0-6fd0d2e33a50",
"materials": [
{
"name": "Material.1",
"metadata": {
"UniqueId": "0638552d-8d1f-4cc6-b540-e8f2eb6429ab"
},
"vop_guid": "e4b8f261-285f-49d5-aae8-3f8709b4a036",
"sop_guids": [
"4333ff7c-a423-4920-85a3-1c29fb589f88"
],
"geometries": {
"geo_paths": [
"TheBodyB",
"TheBodyC"
]
},
"description": "",
"vop": {
"name": "Material.1.VOP",
"opaque": {},
"description": "",
"metadata": {}
},
"sops": [
{
"name": "Material.1.SOP",
"mirror": {
"reflectance": 80.0
},
"description": "",
"metadata": {}
}
]
},
{
"name": "Material.2",
"metadata": {
"UniqueId": "aaabe4a1-ea84-4bf7-b18a-eb30c8a4df70"
},
"vop_guid": "5022d46f-d359-4fa6-89aa-255519444710",
"sop_guids": [
"b127dc7d-8fc0-4f8e-b4a2-07c52fce2a18"
],
"geometries": {
"geo_paths": [
"TheBodyD",
"TheBodyE"
]
},
"description": "",
"vop": {
"name": "Material.2.VOP",
"library": {
"material_file_uri": "/app/assets/AIR.material"
},
"description": "",
"metadata": {}
},
"sops": [
{
"name": "Material.2.SOP",
"optical_polished": {},
"description": "",
"metadata": {}
}
]
},
{
"name": "Material.FOP",
"metadata": {
"UniqueId": "533c0723-222e-45a0-a37b-19d938a89cd9"
},
"sop_guids": [
"c4f11ced-fb0b-4024-9863-c77e9fa056ee"
],
"geometries": {
"geo_paths": [
"TheBodyD/TheFaceF"
]
},
"description": "",
"sops": [
{
"name": "Material.FOP.SOP",
"mirror": {
"reflectance": 90.0
},
"description": "",
"metadata": {}
}
]
},
{
"name": "Material.3",
"metadata": {
"UniqueId": "69467658-301d-43fa-8ab3-b6c5023b1c56"
},
"sop_guids": [
"634ca58f-5e9e-437b-9c97-6e094ee76371"
],
"description": "",
"sops": [
{
"name": "Material.3.SOP",
"mirror": {
"reflectance": 100.0
},
"description": "",
"metadata": {}
}
]
}
],
"name": "",
"description": "",
"metadata": {},
"sources": [],
"sensors": [],
"simulations": [],
"scenes": []
}
Update#
Tipp: if you are manipulating an optical property already committed, don’t forget to commit your changes.
If you don’t, you will still only watch what is committed on the server.
[15]:
print("op1 surface type before update: {}".format(op1.get(key="sops")[0]))
op1.set_volume_optic().set_surface_opticalpolished().commit()
print(op1)
print("op1 surface type after update: {}".format(op1.get(key="sops")[0]))
op1 surface type before update: {'name': 'Material.1.SOP', 'mirror': {'reflectance': 80.0}, 'description': '', 'metadata': {}}
{
"name": "Material.1",
"metadata": {
"UniqueId": "0638552d-8d1f-4cc6-b540-e8f2eb6429ab"
},
"vop_guid": "e4b8f261-285f-49d5-aae8-3f8709b4a036",
"sop_guids": [
"4333ff7c-a423-4920-85a3-1c29fb589f88"
],
"geometries": {
"geo_paths": [
"TheBodyB",
"TheBodyC"
]
},
"description": "",
"vop": {
"name": "Material.1.VOP",
"optic": {
"index": 1.5,
"absorption": 0.0
},
"description": "",
"metadata": {}
},
"sops": [
{
"name": "Material.1.SOP",
"optical_polished": {},
"description": "",
"metadata": {}
}
]
}
op1 surface type after update: {'name': 'Material.1.SOP', 'optical_polished': {}, 'description': '', 'metadata': {}}
Reset#
Possibility to reset local values from the one available in the server.
[16]:
op1.set_surface_mirror() # set surface as a mirror but no commit
op1.reset() # reset -> this will apply the server value to the local value
op1.delete() # delete (to display the local value with the below print)
print(op1)
local: {
"name": "Material.1",
"vop_guid": "",
"geometries": {
"geo_paths": [
"TheBodyB",
"TheBodyC"
]
},
"description": "",
"metadata": {},
"sop_guids": [],
"vop": {
"name": "Material.1.VOP",
"optic": {
"index": 1.5,
"absorption": 0.0
},
"description": "",
"metadata": {}
},
"sops": [
{
"name": "Material.1.SOP",
"optical_polished": {},
"description": "",
"metadata": {}
}
]
}
Delete#
Once the data is deleted from the server, you can still work with local data and maybe commit later.
[17]:
op2.delete()
print(op2)
local: {
"name": "Material.2",
"vop_guid": "",
"geometries": {
"geo_paths": [
"TheBodyD",
"TheBodyE"
]
},
"description": "",
"metadata": {},
"sop_guids": [],
"vop": {
"name": "Material.2.VOP",
"library": {
"material_file_uri": "/app/assets/AIR.material"
},
"description": "",
"metadata": {}
},
"sops": [
{
"name": "Material.2.SOP",
"optical_polished": {},
"description": "",
"metadata": {}
}
]
}
Clean up all Optical properties
[18]:
op1.delete()
op3.delete()
op4.delete()
[18]:
<ansys.speos.core.opt_prop.OptProp at 0x7f0b927b5960>
[19]:
speos.close()
[19]:
True