|
| 1 | +Launching and connecting to a Modeler instance |
| 2 | +********************************************** |
| 3 | + |
| 4 | +PyAnsys Geometry provides the ability to launch and connect to a Modeler instance |
| 5 | +either locally or remotely. A Modeler instance is a running instance of a |
| 6 | +CAD service that the PyAnsys Geometry client can communicate with. |
| 7 | + |
| 8 | +CAD services that are supported include: |
| 9 | + |
| 10 | +- Ansys Geometry Service |
| 11 | +- Ansys Discovery |
| 12 | +- Ansys SpaceClaim |
| 13 | + |
| 14 | +Connecting to a Modeler instance |
| 15 | +-------------------------------- |
| 16 | + |
| 17 | +To connect to a Modeler instance, you can use the :class:`Modeler() <ansys.geometry.core.modeler>` class, |
| 18 | +which provides methods to connect to the desired CAD service. You can specify the connection parameters such |
| 19 | +as the host, port, and authentication details. |
| 20 | + |
| 21 | +.. code:: python |
| 22 | +
|
| 23 | + from ansys.geometry.core import Modeler |
| 24 | +
|
| 25 | + # Connect to a local Modeler instance |
| 26 | + modeler = Modeler(host="localhost", port=12345) |
| 27 | +
|
| 28 | +Connection types |
| 29 | +---------------- |
| 30 | + |
| 31 | +PyAnsys Geometry supports different connection types to connect to a Modeler instance, which |
| 32 | +differ in the environment in which the transport takes place: |
| 33 | + |
| 34 | +- **Local connection**: The Modeler instance is running on the same machine as the PyAnsys |
| 35 | + Geometry client. This is typically used for development and testing purposes. |
| 36 | +- **Remote connection**: The service instance is running on a different machine, and the |
| 37 | + Modeler client connects to it over the network. This is useful for accessing |
| 38 | + Modeler instances hosted on remote servers or cloud environments. |
| 39 | + |
| 40 | +Securing connections |
| 41 | +-------------------- |
| 42 | + |
| 43 | +When connecting to a remote Modeler instance, it is important to ensure that the connection |
| 44 | +is secure, not only to protect sensitive data but also to comply with organizational |
| 45 | +security policies. These secure connections can be established using various methods, such as: |
| 46 | + |
| 47 | +- **mTLS**: Mutual Transport Layer Security (mTLS) is a security protocol that ensures both the client |
| 48 | + and server authenticate each other using digital certificates. This provides a high level of |
| 49 | + security for the connection. PyAnsys Geometry supports mTLS connections to Modeler instances. In that |
| 50 | + case, you need to provide the necessary certificates and keys when establishing the connection. More |
| 51 | + information on the certificates needed can be seen in |
| 52 | + `Generating certificates for mTLS <https://tools.docs.pyansys.com/version/stable/user_guide/secure_grpc.html#generating-certificates-for-mtls>`_. |
| 53 | + Make sure that the names of the files are in line with the previous link. An example of how to set up |
| 54 | + an mTLS connection is shown below: |
| 55 | + |
| 56 | + .. note:: |
| 57 | + |
| 58 | + mTLS is the default transport mode when connecting to remote Modeler instances. |
| 59 | + |
| 60 | + .. code:: python |
| 61 | +
|
| 62 | + from ansys.geometry.core import Modeler, launch_modeler |
| 63 | +
|
| 64 | + # OPTION 1: Connect to a Modeler instance using mTLS |
| 65 | + modeler = Modeler( |
| 66 | + host="remote_host", |
| 67 | + port=12345, |
| 68 | + transport_mode="mtls", |
| 69 | + certs_dir="path/to/certs_directory", |
| 70 | + ) |
| 71 | +
|
| 72 | + # OPTION 2: Launch the Modeler instance locally using mTLS |
| 73 | + modeler = launch_modeler( |
| 74 | + transport_mode="mtls", |
| 75 | + certs_dir="path/to/certs_directory", |
| 76 | + ) |
| 77 | +
|
| 78 | +- **UDS**: Unix Domain Sockets (UDS) provide a way to establish secure connections between |
| 79 | + processes on the same machine. UDS connections are faster and more secure than traditional |
| 80 | + network connections, as they do not require network protocols. PyAnsys Geometry supports UDS |
| 81 | + connections to local Modeler instances (**only on Linux-based services**). An example of how |
| 82 | + to set up a UDS connection is shown below: |
| 83 | + |
| 84 | + .. note:: |
| 85 | + |
| 86 | + UDS is only supported when connecting to local Modeler instances on Linux-based services. |
| 87 | + It is also the default transport mode in such cases. |
| 88 | + |
| 89 | + .. code:: python |
| 90 | +
|
| 91 | + from ansys.geometry.core import Modeler, launch_modeler |
| 92 | +
|
| 93 | + # OPTION 1: Connect to a local Modeler instance using UDS |
| 94 | + modeler = Modeler(host="localhost", port=12345, transport_mode="uds") |
| 95 | +
|
| 96 | + # OPTION 2: Launch the Modeler instance locally using UDS and specific directory and id for |
| 97 | + # the UDS socket |
| 98 | + modeler = Modeler(host="localhost", port=12345, transport_mode="uds", uds_dir="/path/to/uds_directory", uds_id="unique_id") |
| 99 | +
|
| 100 | + # OPTION 3: Launch the Modeler instance locally using UDS |
| 101 | + modeler = launch_modeler(transport_mode="uds") |
| 102 | +
|
| 103 | + # OPTION 4: Launch the Modeler instance locally using UDS and specific directory and id for |
| 104 | + # the UDS socket |
| 105 | + modeler = launch_modeler(transport_mode="uds", uds_dir="/path/to/uds_directory", uds_id="unique_id") |
| 106 | +
|
| 107 | +- **WNUA**: Windows Named User Authentication (WNUA) provides a way to establish secure connections |
| 108 | + between processes on the same Windows machine. WNUA connections use a built-in mechanism to verify |
| 109 | + that the owner of the service running is also the owner of the client connection established (similar |
| 110 | + to UDS). PyAnsys Geometry supports WNUA connections to local Modeler instances |
| 111 | + (**only on Windows-based services**). An example of how to set up a WNUA connection is shown below: |
| 112 | + |
| 113 | + .. note:: |
| 114 | + |
| 115 | + WNUA is only supported when connecting to local Modeler instances on Windows-based services. |
| 116 | + It is also the default transport mode in such cases. |
| 117 | + |
| 118 | + .. code:: python |
| 119 | +
|
| 120 | + from ansys.geometry.core import Modeler, launch_modeler |
| 121 | +
|
| 122 | + # OPTION 1: Connect to a local Modeler instance using WNUA |
| 123 | + modeler = Modeler(host="localhost", port=12345, transport_mode="wnua") |
| 124 | +
|
| 125 | + # OPTION 2: Launch the Modeler instance locally using WNUA |
| 126 | + modeler = launch_modeler(transport_mode="wnua") |
| 127 | +
|
| 128 | +- **Insecure**: Insecure connections do not provide any security measures to protect the data |
| 129 | + transmitted between the client and server. This mode is not recommended for production use, |
| 130 | + as it exposes the connection to potential security risks. However, it can be useful for |
| 131 | + development and testing purposes in trusted environments. An example of how to set up an |
| 132 | + insecure connection is shown below: |
| 133 | + |
| 134 | + .. code:: python |
| 135 | +
|
| 136 | + from ansys.geometry.core import Modeler, launch_modeler |
| 137 | +
|
| 138 | + # OPTION 1: Connect to a Modeler instance using an insecure connection |
| 139 | + modeler = Modeler( |
| 140 | + host="remote_host", |
| 141 | + port=12345, |
| 142 | + transport_mode="insecure", |
| 143 | + ) |
| 144 | +
|
| 145 | + # OPTION 2: Launch the Modeler instance locally using an insecure connection |
| 146 | + modeler = launch_modeler( |
| 147 | + transport_mode="insecure", |
| 148 | + ) |
| 149 | +
|
| 150 | +For more information on secure connections and transport modes, see |
| 151 | +`Securing gRPC connections <https://tools.docs.pyansys.com/version/stable/user_guide/secure_grpc.html>`_. |
0 commit comments