docs: remote instance

doc/changelog.d/553.documentation.md

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

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/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