Skip to content

docs: adjust source example #543

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Apr 8, 2025
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/changelog.d/543.documentation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
adjust source example
126 changes: 66 additions & 60 deletions examples/core/source.py
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
# # How to create a source

# This tutorial demonstrates how to create a source.

#
# There are different type of sources available: luminaire source, surface source, ray file source.

# ## Prerequisites
#
# ### Perform imports
# +
from pathlib import Path

Expand All @@ -14,132 +17,135 @@
SourceSurface,
)

# If using docker container
assets_data_path = Path("/app") / "assets"
# If using local server
# assets_data_path = Path().resolve().parent.parent / "tests" / "assets"
# If using a different path
# assets_data_path = Path("path/to/downloaded/example/assets")
# -

# ## Create connection with speos rpc server
# ### Define constants
# Constants help ensure consistency and avoid repetition throughout the example.

# +
speos = Speos(host="localhost", port=50098)
# -
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.
IES = "IES_C_DETECTOR.ies"

# ## Create a new project
# ## Model Setup
#
# ### Load assets
# The assets used to run this example are available in the
# [PySpeos repository](https://github.com/ansys/pyspeos/) on GitHub.
#
# > **Note:** Make sure you
# > have downloaded simulation assets and set ``assets_data_path``
# > to point to the assets folder.

# The only way to create a source, is to create it from a project.
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.

speos = Speos(host=HOSTNAME, port=GRPC_PORT)

# ### Create a new project
#
# The only way to create a source using the core layer, is to create it from a project.
# The ``Project`` class is instantiated by passing a ``Speos`` instance

# +
p = Project(speos=speos)
print(p)
# -

# ## Create

# Create locally

# The mention "local: " is added when printing the source.
# ### Source Creation
#
# #### Create locally
# The mention "local: " is added when printing the source data and information is not yet
# pushed to the RPC server

# +
intensity_file_path = str(assets_data_path / "IES_C_DETECTOR.ies")

intensity_file_path = str(assets_data_path / IES)
source1 = p.create_source(name="Luminaire.1", feature_type=SourceLuminaire) # type luminaire
source1.set_intensity_file_uri(uri=intensity_file_path)
print(source1)
# -

# ## Push it to the server.

# Now that it is committed to the server, the mention "local: " is no more present when printing the
# #### Push it to the server.
#
# After it is committed to the server, the mention "local: " is no more present when printing the
# source.

# +
source1.commit()
print(source1)
# -

# ## Another example

# #### Changing additional Source Properties
#
# Setting several more characteristics.

# +
intensity_file_path = str(assets_data_path / "IES_C_DETECTOR.ies")

intensity_file_path = str(assets_data_path / IES)
source2 = p.create_source(name="Luminaire.2", feature_type=SourceLuminaire)
source2.set_intensity_file_uri(uri=intensity_file_path)
source2.set_flux_radiant() # select flux radiant with default value
# choose the source location [Origin, Xvector, Yvector, Zvector]
source2.set_axis_system(axis_system=[20, 50, 10, 1, 0, 0, 0, 1, 0, 0, 0, 1])
source2.set_spectrum().set_blackbody() # choose blacbody with default value for the source spectrum
source2.set_spectrum().set_blackbody() # choose blackbody with default value for the spectrum
source2.commit() # Push to the server
print(source2)
# -

# ## Read

# ### Source Instance

# #### Source Instance
#
# As mention "local: " is added if it is not yet committed to the server.

# +
print(source1)
# -

# ### Project

# #### Project
#
# Committed feature will appear inside the project information.

# +
print(p)
# -

# ## Update

# #### Update
#
# Tipp: if you are manipulating a source already committed, don't forget to commit your changes.

#
# If you don't, you will still only watch what is committed on the server.

# +
source1.set_flux_radiant(value=1.2) # modify radiant flux value
source1.set_axis_system(axis_system=[17, 10, 10, 1, 0, 0, 0, 1, 0, 0, 0, 1]) # modify axis system
source1.set_spectrum().set_halogen() # modify spectrum by choosing halogen
source1.commit() # Push changes to the server
print(source1)
# -

# ## Reset

# #### Reset
#
# Possibility to reset local values from the one available in the server.

# +
source1.set_flux_luminous() # modify to luminous flux BUT no commit
source1.reset()
# reset -> this will apply the server value to the local value the local value will be back to
# halogen
source1.delete() # delete (to display the local value with the below print)
print(source1)
# -

# ## Delete

# #### Delete
#
# Once the data is deleted from the server, you can still work with local data and maybe commit
# later.

# +
source2.delete()
print(source2)
# -

# +
source1.delete()
print(p)
# -

# ## Other Sources Examples
# ### Other Sources Examples

# ### ray-file source
# #### Ray-file source

# +
ray_file_path = str(assets_data_path / "Rays.ray")
Expand All @@ -160,7 +166,7 @@
source3.delete()
# -

# ### surface source
# #### Surface source

# +
source4 = p.create_source(name="Surface.1", feature_type=SourceSurface)
Expand Down Expand Up @@ -189,10 +195,10 @@
# -

# When creating sources, this creates some intermediate objects (spectrums, intensity templates).

#
# Deleting a source does not delete in cascade those objects
# because they could be used by some other entities from core layer.

#
# Then at the end of the example, we just clean all databases

# +
Expand Down