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": "901d4498-db98-4903-b4e0-b4ae4911faf5"
},
"vop_guid": "a9aaf645-1548-4c91-a676-19a4f60ddf38",
"sop_guids": [
"2bb22673-25f7-4751-afc1-e7632a1523d1"
],
"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": "a8a63a68-5db6-4f7c-a5c0-4c688b7f5dad"
},
"vop_guid": "a8457ce1-cf7b-4212-a991-a720bf3bf9cd",
"sop_guids": [
"84fd311b-9441-47fe-9c22-9c48b3ea8ad8"
],
"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": "ac407e12-6a67-4cc8-9617-e7fa01010b27"
},
"sop_guids": [
"4ba7657d-0579-416c-80fd-2ef34d2e72f0"
],
"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": "8aad97d3-a4fb-4942-bdd8-b0de54a32b63"
},
"sop_guids": [
"bfe963ed-74a7-4338-9e99-b53b84642413"
],
"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": "901d4498-db98-4903-b4e0-b4ae4911faf5"
},
"vop_guid": "a9aaf645-1548-4c91-a676-19a4f60ddf38",
"sop_guids": [
"2bb22673-25f7-4751-afc1-e7632a1523d1"
],
"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": "a8a63a68-5db6-4f7c-a5c0-4c688b7f5dad"
},
"vop_guid": "a8457ce1-cf7b-4212-a991-a720bf3bf9cd",
"sop_guids": [
"84fd311b-9441-47fe-9c22-9c48b3ea8ad8"
],
"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": "ac407e12-6a67-4cc8-9617-e7fa01010b27"
},
"sop_guids": [
"4ba7657d-0579-416c-80fd-2ef34d2e72f0"
],
"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": "d3ada57b-2d67-49be-8963-b227f35047e6",
"materials": [
{
"name": "Material.1",
"metadata": {
"UniqueId": "901d4498-db98-4903-b4e0-b4ae4911faf5"
},
"vop_guid": "a9aaf645-1548-4c91-a676-19a4f60ddf38",
"sop_guids": [
"2bb22673-25f7-4751-afc1-e7632a1523d1"
],
"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": "a8a63a68-5db6-4f7c-a5c0-4c688b7f5dad"
},
"vop_guid": "a8457ce1-cf7b-4212-a991-a720bf3bf9cd",
"sop_guids": [
"84fd311b-9441-47fe-9c22-9c48b3ea8ad8"
],
"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": "ac407e12-6a67-4cc8-9617-e7fa01010b27"
},
"sop_guids": [
"4ba7657d-0579-416c-80fd-2ef34d2e72f0"
],
"geometries": {
"geo_paths": [
"TheBodyD/TheFaceF"
]
},
"description": "",
"sops": [
{
"name": "Material.FOP.SOP",
"mirror": {
"reflectance": 90.0
},
"description": "",
"metadata": {}
}
]
},
{
"name": "Material.3",
"metadata": {
"UniqueId": "8aad97d3-a4fb-4942-bdd8-b0de54a32b63"
},
"sop_guids": [
"bfe963ed-74a7-4338-9e99-b53b84642413"
],
"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": "901d4498-db98-4903-b4e0-b4ae4911faf5"
},
"vop_guid": "a9aaf645-1548-4c91-a676-19a4f60ddf38",
"sop_guids": [
"2bb22673-25f7-4751-afc1-e7632a1523d1"
],
"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 0x7fcdb07bf8e0>
[19]:
speos.close()
[19]:
True