From 2858d3fb46ba09ddc0e1b51efff805382b3d7eec Mon Sep 17 00:00:00 2001 From: sthoene Date: Mon, 7 Apr 2025 17:43:29 +0200 Subject: [PATCH 1/6] adjust source example --- examples/core/source.py | 126 +++++++++++++++++++++------------------- 1 file changed, 66 insertions(+), 60 deletions(-) diff --git a/examples/core/source.py b/examples/core/source.py index d5d42c333..f56333669 100644 --- a/examples/core/source.py +++ b/examples/core/source.py @@ -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 @@ -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") @@ -160,7 +166,7 @@ source3.delete() # - -# ### surface source +# #### Surface source # + source4 = p.create_source(name="Surface.1", feature_type=SourceSurface) @@ -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 # + From 51c42566f50b07ee4dad68a3fdc740a4ec89cabc Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Tue, 8 Apr 2025 06:05:18 +0000 Subject: [PATCH 2/6] chore: adding changelog file 543.documentation.md [dependabot-skip] --- doc/changelog.d/543.documentation.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changelog.d/543.documentation.md diff --git a/doc/changelog.d/543.documentation.md b/doc/changelog.d/543.documentation.md new file mode 100644 index 000000000..b096d7ef7 --- /dev/null +++ b/doc/changelog.d/543.documentation.md @@ -0,0 +1 @@ +adjust source example \ No newline at end of file From c25a639bfc9739d84bf985b80d93642df92d3712 Mon Sep 17 00:00:00 2001 From: sthoene Date: Tue, 8 Apr 2025 10:45:46 +0200 Subject: [PATCH 3/6] improve code coverage --- examples/core/source.py | 38 ++++++++++++++++++-------------------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/examples/core/source.py b/examples/core/source.py index f56333669..cfedbfdb0 100644 --- a/examples/core/source.py +++ b/examples/core/source.py @@ -4,9 +4,9 @@ # # There are different type of sources available: luminaire source, surface source, ray file source. -# ## Prerequisites +# ### Prerequisites # -# ### Perform imports +# ## Perform imports # + from pathlib import Path @@ -19,7 +19,7 @@ # - -# ### Define constants +# ## Define constants # Constants help ensure consistency and avoid repetition throughout the example. HOSTNAME = "localhost" @@ -27,9 +27,9 @@ USE_DOCKER = True # Set to False if you're running this example locally as a Notebook. IES = "IES_C_DETECTOR.ies" -# ## Model Setup +# ### Model Setup # -# ### Load assets +# ## Load assets # The assets used to run this example are available in the # [PySpeos repository](https://github.com/ansys/pyspeos/) on GitHub. # @@ -42,7 +42,7 @@ else: assets_data_path = Path("/path/to/your/download/assets/directory") -# ### Connect to the RPC Server +# ## 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 @@ -50,7 +50,7 @@ speos = Speos(host=HOSTNAME, port=GRPC_PORT) -# ### Create a new project +# ## 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 @@ -59,20 +59,18 @@ print(p) -# ### Source Creation +# ## Source Creation # -# #### Create locally +# **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) 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. +# **Push it to the server.** # # After it is committed to the server, the mention "local: " is no more present when printing the # source. @@ -80,7 +78,7 @@ source1.commit() print(source1) -# #### Changing additional Source Properties +# **Changing additional Source Properties** # # Setting several more characteristics. @@ -95,19 +93,19 @@ source2.commit() # Push to the server print(source2) -# #### 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. # @@ -119,7 +117,7 @@ source1.commit() # Push changes to the server print(source1) -# #### Reset +# **Reset** # # Possibility to reset local values from the one available in the server. @@ -131,7 +129,7 @@ print(source1) -# #### Delete +# **Delete** # # Once the data is deleted from the server, you can still work with local data and maybe commit # later. @@ -145,7 +143,7 @@ # ### Other Sources Examples -# #### Ray-file source +# ## Ray-file source # + ray_file_path = str(assets_data_path / "Rays.ray") @@ -166,7 +164,7 @@ source3.delete() # - -# #### Surface source +# ## Surface source # + source4 = p.create_source(name="Surface.1", feature_type=SourceSurface) From 81dff70eadc74f66dd3f0f8a0de6bb650787f369 Mon Sep 17 00:00:00 2001 From: sthoene Date: Tue, 8 Apr 2025 11:16:07 +0200 Subject: [PATCH 4/6] Adjust Example --- examples/core/source.py | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/examples/core/source.py b/examples/core/source.py index cfedbfdb0..92323ef85 100644 --- a/examples/core/source.py +++ b/examples/core/source.py @@ -3,10 +3,11 @@ # 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 +# ## Prerequisites +# +# ### Perform imports + # + from pathlib import Path @@ -19,7 +20,7 @@ # - -# ## Define constants +# ### Define constants # Constants help ensure consistency and avoid repetition throughout the example. HOSTNAME = "localhost" @@ -27,9 +28,9 @@ USE_DOCKER = True # Set to False if you're running this example locally as a Notebook. IES = "IES_C_DETECTOR.ies" -# ### Model Setup +# ## Model Setup # -# ## Load assets +# ### Load assets # The assets used to run this example are available in the # [PySpeos repository](https://github.com/ansys/pyspeos/) on GitHub. # @@ -42,7 +43,7 @@ else: assets_data_path = Path("/path/to/your/download/assets/directory") -# ## Connect to the RPC Server +# ### 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 @@ -50,7 +51,7 @@ speos = Speos(host=HOSTNAME, port=GRPC_PORT) -# ## Create a new project +# ### 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 @@ -59,9 +60,9 @@ print(p) -# ## Source Creation +# ### Source Creation # -# **Create locally** +# **Create locally:** # The mention "local: " is added when printing the source data and information is not yet # pushed to the RPC server @@ -99,13 +100,13 @@ 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. # @@ -141,9 +142,9 @@ print(p) # - -# ### Other Sources Examples +# ## Other Sources Examples -# ## Ray-file source +# ### Ray-file source # + ray_file_path = str(assets_data_path / "Rays.ray") @@ -164,7 +165,7 @@ source3.delete() # - -# ## Surface source +# ### Surface source # + source4 = p.create_source(name="Surface.1", feature_type=SourceSurface) From 25fd272b3781fe2cf107c5d9f8561dd72de85848 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Th=C3=B6ne?= <86405327+StefanThoene@users.noreply.github.com> Date: Tue, 8 Apr 2025 14:43:37 +0200 Subject: [PATCH 5/6] Apply suggestions from code review --- examples/core/source.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/core/source.py b/examples/core/source.py index 92323ef85..f1dcddbc0 100644 --- a/examples/core/source.py +++ b/examples/core/source.py @@ -106,11 +106,11 @@ 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. +# > **Note:** 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 From b8180bd32f3f8cc6deed15e01f00ce74880187fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Th=C3=B6ne?= <86405327+StefanThoene@users.noreply.github.com> Date: Tue, 8 Apr 2025 15:12:48 +0200 Subject: [PATCH 6/6] fix precommit --- examples/core/source.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/core/source.py b/examples/core/source.py index f1dcddbc0..aeb6aa536 100644 --- a/examples/core/source.py +++ b/examples/core/source.py @@ -108,8 +108,8 @@ # **Update:** # -# > **Note:** if you are manipulating a source already committed, don't forget to commit your changes. -# > +# > **Note:** 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