Merge branch 'main' into pre-commit-ci-update-config

Author: StefanThoene

doc/changelog.d/454.added.md

@@ -0,0 +1 @@
+Feat/add local launcher

doc/changelog.d/553.documentation.md

@@ -0,0 +1 @@
+remote instance

doc/changelog.d/555.dependencies.md

@@ -0,0 +1 @@
+bump psutil from 6.1.1 to 7.0.0

doc/source/cheat_sheet/cheat_sheet_script.qmd

@@ -35,13 +35,23 @@ jupyter:
 
 # Connect to Speos Service
 
-Connect to an instance locally:
+Start instance locally:
 
 ```{python}
 #| eval: false
-from ansys.speos.core import Speos
+from ansys.speos.core.launcher import launch_local_speos_rpc_server
+
+speos_server = launch_local_speos_rpc_server()
+# returns a connected speos instance
+```
+
+Connect to an existing instance:
 
-speos_server = Speos(host='127.0.0.1', port=50098)
+```{python}
+#| eval: false
+from ansys.speos.core import Speos
+host_ip = '127.0.0.1' # localhost here
+speos_server = Speos(host=host_ip, port=50098)
 ```
 
 # Speos Solver files

doc/source/getting_started/index.rst

@@ -31,21 +31,14 @@ containers. Select the option that best suits your needs.
             Launch the Speos service as a Docker container
             and connect to it from PySpeos.
 
-   .. grid-item-card:: Local service
-            :link: local/index
+   .. grid-item-card:: Launch a service
+            :link: launcher/index
             :link-type: doc
 
-            Launch the Speos service locally on your machine
+            Launch the Speos service locally or remotely on a Computer
             and connect to it from PySpeos.
 
-   .. grid-item-card:: Remote service
-            :link: remote/index
-            :link-type: doc
-
-            Launch the Speos service on a remote machine and
-            connect to it using PIM (Product Instance Manager).
-
-   .. grid-item-card:: Connect to an existing service
+   .. grid-item-card:: Use an existing service
             :link: existing/index
             :link-type: doc
 

doc/source/getting_started/launcher/index.rst

@@ -0,0 +1,147 @@
+.. _ref_creating_local_service:
+
+Launch a service
+================
+
+To launch a Speos service you have several options:
+
+* Use python launch method to start it locally
+* Use Bash to start it yourself
+* Rely on Ansys PIM to start a service
+
+Python launcher
+---------------
+
+To launch a local Speos RPC server instance use:
+
+.. code:: python
+
+    from ansys.speos.core.launcher import launch_local_speos_rpc_server
+
+    speos = launch_local_speos_rpc_server(version='251')
+
+You receive a ``Speos`` object in return that you then use as a Speos session.
+For more information you can look at the API Reference.
+
+.. button-ref:: ../../api/ansys/speos/core/launcher/index
+    :ref-type: doc
+    :color: primary
+    :shadow:
+
+
+The session can be ended via the object ``Speos`` like this:
+
+.. code:: python
+
+    speos.close()
+
+Launch a local service from the command line
+--------------------------------------------
+
+To launch the service, you need to use the following commands:
+
+.. tab-set::
+
+    .. tab-item:: Windows CMD
+
+        .. code-block:: bash
+
+            "%AWP_ROOT251%\Optical Products\SPEOS_RPC\SpeosRPC_Server.exe"
+
+    .. tab-item:: Windows Powershell
+
+        .. code-block:: bash
+
+            & "$env:AWP_ROOT251\Optical Products\SPEOS_RPC\SpeosRPC_Server.exe"
+
+    .. tab-item:: Linux
+
+        .. code-block:: bash
+
+            $AWP_ROOT251/OpticalProducts/SPEOS_RPC/SpeosRPC_Server.x
+
+
+To stop the server you can use the following command line:
+
+.. tab-set::
+
+    .. tab-item:: Windows CMD
+
+        .. code-block:: bash
+
+            "%AWP_ROOT251%\Optical Products\SPEOS_RPC\SpeosRPC_Server.exe --stop portNumber"
+
+    .. tab-item:: Windows Powershell
+
+        .. code-block:: bash
+
+            & "$env:AWP_ROOT251\Optical Products\SPEOS_RPC\SpeosRPC_Server.exe --stop portNumber"
+
+    .. tab-item:: Linux
+
+        .. code-block:: bash
+
+            $AWP_ROOT251/OpticalProducts/SPEOS_RPC/SpeosRPC_Server.x --stop portNumber
+
+To see all the command line parameters you can use the help flag:
+
+.. tab-set::
+
+    .. tab-item:: Windows CMD
+
+        .. code-block:: bash
+
+            "%AWP_ROOT251%\Optical Products\SPEOS_RPC\SpeosRPC_Server.exe --help"
+
+    .. tab-item:: Windows Powershell
+
+        .. code-block:: bash
+
+            & "$env:AWP_ROOT251\Optical Products\SPEOS_RPC\SpeosRPC_Server.exe --help"
+
+    .. tab-item:: Linux
+
+        .. code-block:: bash
+
+            $AWP_ROOT251/OpticalProducts/SPEOS_RPC/SpeosRPC_Server.x --help
+
+Use PySpeos launcher with PIM
+-----------------------------
+
+If a remote server is running Ansys Release 2025 R1 or later and is also running PIM (Product
+Instance Manager), you can use PIM to start a SpeosRPC server Session that PySpeos
+can connect to.
+
+A usage example of the remote service can be accessed via AnsysLAB.
+
+.. warning::
+
+   **This option is only available for Ansys employees.**
+
+   Only Ansys employees with credentials to the Artifact Repository Browser
+   can download ZIP files for PIM.
+
+To launch a remote Speos service:
+
+.. code:: python
+
+    from ansys.speos.core import launcher
+
+    speos = launcher.launch_speos("251")
+
+The preceding commands launch a remote Speos service (version 2025 R1).
+You receive a ``Speos`` object in return that you then use as a Speos session.
+
+The session can be ended via the object ``Speos`` like this:
+
+.. code:: python
+
+    speos.close()
+
+.. button-ref:: ../index
+    :ref-type: doc
+    :color: primary
+    :shadow:
+    :expand:
+
+    Go to Getting started

doc/source/getting_started/local/index.rst

@@ -38,6 +38,7 @@ PySpeos documentation |version|
         Learn how to use PySpeos with examples that demonstrate its capabilities.
 
     .. grid-item-card:: Contribute :fa:`people-group`
+        :padding: 2 2 2 2
         :link: contributing
         :link-type: doc
 

doc/source/getting_started/remote/index.rst

@@ -31,6 +31,7 @@ dependencies=[
     "grpcio>=1.50.0,<1.71",
     "grpcio-health-checking>=1.45.0,<1.68",
     "ansys-api-speos==0.14.2",
+    "ansys-tools-path>=0.3.1",
     "numpy>=1.20.3,<3",
     "comtypes>=1.4,<1.5",
 ]
@@ -41,6 +42,7 @@ graphics = [
     "ansys-tools-visualization-interface>=0.8.3",
 ]
 tests = [
+    "psutil==7.0.0",
     "pytest==8.3.5",
     "pyvista>=0.40.0,<0.45",
     "ansys-tools-visualization-interface>=0.8.3",

doc/source/index.rst

@@ -0,0 +1,36 @@
+# Copyright (C) 2021 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Collection of all constants used in pySpeos."""
+
+import os
+
+DEFAULT_HOST = "localhost"
+"""Default host used by Speos RPC server and client """
+DEFAULT_PORT = "50098"
+"""Default port used by Speos RPC server and client """
+DEFAULT_VERSION = "251"
+"""Latest supported Speos version of the current PySpeos Package"""
+MAX_MESSAGE_LENGTH = int(os.environ.get("SPEOS_MAX_MESSAGE_LENGTH", 256 * 1024**2))
+"""Maximum message length value accepted by the Speos RPC server,
+By default, value stored in environment variable SPEOS_MAX_MESSAGE_LENGTH or 268 435 456.
+"""