docs: Update file transfer docs

[hpohekar]

closes #3907

Update file transfer docs.

[seanpearsonuk]

AS a PyFluent user, what is the advantage gained if I use the local service versus using no service?

[hpohekar]

AS a PyFluent user, what is the advantage gained if I use the local service versus using no service?

@seanpearsonuk User can specify remote file name while uploading and local directory while downloading the Fluent files.

cc: @mkundu1

[seanpearsonuk]

Hi @hpohekar, thanks for putting this together. I think the documentation has a good foundation, but it currently undersells the feature and misses the opportunity to highlight its most user-friendly capabilities. A few thoughts and suggestions:

• The opening sentence refers to “the file transfer service,” but later we learn there are multiple services. It would help to introduce this upfront with a more general framing.

• The introduction doesn’t mention the key benefit: when a file transfer service is used, upload() and download() calls are often unnecessary—file operations like read_case and write_case just work. That’s a clear benefit in terms of usability, and we should point it out early.

• The paragraph that starts “You have the option to specify a different name…” is a bit long and indirectly written. It’s describing behavior specific to upload() and download(), but those methods aren’t mentioned by name. We could split this into shorter, clearer bullet points or concise lines that name the methods directly.

• The code reference launch_fluent(file_transfer_service=<name_of_the_file_transfer_service>) should be formatted consistently, probably as a code block or inline code.

• The sentence about defining your own file transfer service (“You can define your own…”) feels premature if we’re not showing how to do that in the doc. Unless we’re planning to add an example or guidance for this, we might want to omit that line for now.

• Question: Is it truly the case that the Remote file transfer service is only applicable when running in container mode? If not, we should revise that statement.

• The Remote file transfer section dives straight into gRPC implementation details without first describing why a user would want to use it. I’d recommend briefly framing its purpose or benefit first.

• Similarly, for the Local file transfer service, it would help to explain what this is in practical terms, and why a user might choose it—i.e., “use this if you're running Fluent locally in standalone mode,” etc.

• The examples still contain explicit upload() and download() calls, even where file operations would work seamlessly without them. This could confuse users into thinking those calls are always required. Can we trim or annotate the examples accordingly?

• The large “Examples” headings break the structure awkwardly now that we’re splitting the examples per service. Consider removing or replacing with something more descriptive like “Example: Using the Local File Transfer Service”.

• Finally, naming-wise: file_transfer_service=LocalFileTransferStrategy() and similar is a bit clunky. I’m not sure what the best solution is, but maybe a more user-facing alias could be introduced?

I used Chat GPT to help make some improvements based on the above points and the following code block should be used as a basis. However, it is crucial to proof-read it for inaccuracies as I can see that some things look a bit off the mark (it lacks complete context) while I already corrected some other details.

.. _ref_file_transfer_guide:

File transfer
=============

PyFluent provides a file transfer service that manages how files are uploaded to and downloaded from the Fluent server.  
This service allows file-based API methods like `read_case()` and `write_mesh()` to work seamlessly—even when Fluent is running remotely, in a container, or in a PIM-managed environment.

Depending on how Fluent is launched, different file transfer strategies are available:

1. **Local file transfer service**

   When Fluent is launched in standalone mode on the same machine as the Python client, files can be accessed directly from the local file system. In this case, the local file transfer service is used.

   Use this service when:
   - Fluent is running locally.
   - You want to ensure explicit control over file movement using `upload()` and `download()`.

   Example:

   .. code-block:: python

      >>> import ansys.fluent.core as pyfluent
      >>> from ansys.fluent.core import examples
      >>> from ansys.fluent.core.utils.file_transfer_service import LocalFileTransferStrategy

      >>> mesh_file = examples.download_file("mixing_elbow.msh.h5", "pyfluent/mixing_elbow")

      >>> session = pyfluent.launch_fluent(mode=pyfluent.FluentMode.MESHING, 
      ...                                   file_transfer_service=LocalFileTransferStrategy())
      >>> session.upload(file_name=mesh_file, remote_file_name="elbow.msh.h5")
      >>> session.meshing.File.ReadMesh(FileName="elbow.msh.h5")
      >>> session.meshing.File.WriteMesh(FileName="write_elbow.msh.h5")
      >>> session.download(file_name="write_elbow.msh.h5", local_directory="<local_path>")

2. **Remote file transfer service**

   When Fluent runs in a Docker container or another remote environment, files cannot be shared directly between client and server.  
   The remote file transfer service uses a gRPC-based mechanism to manage transfers.

   Use this service when:
   - Fluent is running in container mode or remotely.
   - You need to transfer files explicitly between environments.

   Example:

   .. code-block:: python

      >>> import ansys.fluent.core as pyfluent
      >>> from ansys.fluent.core import examples
      >>> from ansys.fluent.core.utils.file_transfer_service import RemoteFileTransferStrategy

      >>> case_file = examples.download_file("mixing_elbow.cas.h5", "pyfluent/mixing_elbow")

      >>> session = pyfluent.launch_fluent(file_transfer_service=RemoteFileTransferStrategy())
      >>> session.upload(file_name=case_file, remote_file_name="elbow.cas.h5")
      >>> session.file.read_case(file_name="elbow.cas.h5")
      >>> session.file.write_case(file_name="write_elbow.cas.h5")
      >>> session.download(file_name="write_elbow.cas.h5", local_directory="<local_path>")

3. **PIM file transfer service**

   When launching Fluent through the Product Instance Management (PIM), file transfer is fully automated.  
   You don’t need to call `upload()` or `download()`—files are transferred transparently when you use file-based API methods.

   Use this service when:
   - You launch Fluent using PIM.
   - You want seamless file transfers without needing to manage them directly.

   Example:

   .. code-block:: python

      >>> import ansys.fluent.core as pyfluent
      >>> from ansys.fluent.core import examples

      >>> case_file = examples.download_file("mixing_elbow.cas.h5", "pyfluent/mixing_elbow")

      >>> session = pyfluent.launch_fluent()
      >>> session.file.read_case(file_name=case_file)
      >>> session.file.write_case(file_name="write_mixing_elbow.cas.h5")

Defining your own file transfer service
---------------------------------------

Advanced users can define a custom file transfer strategy and use it when launching Fluent:

.. code-block:: python

   >>> pyfluent.launch_fluent(file_transfer_service=<your_custom_strategy>)

(Instructions for creating a custom strategy are beyond the scope of this guide.)

[hpohekar]

Hi @hpohekar, thanks for putting this together. I think the documentation has a good foundation, but it currently undersells the feature and misses the opportunity to highlight its most user-friendly capabilities. A few thoughts and suggestions:

• The opening sentence refers to “the file transfer service,” but later we learn there are multiple services. It would help to introduce this upfront with a more general framing.
• The introduction doesn’t mention the key benefit: when a file transfer service is used, upload() and download() calls are often unnecessary—file operations like read_case and write_case just work. That’s a clear benefit in terms of usability, and we should point it out early.
• The paragraph that starts “You have the option to specify a different name…” is a bit long and indirectly written. It’s describing behavior specific to upload() and download(), but those methods aren’t mentioned by name. We could split this into shorter, clearer bullet points or concise lines that name the methods directly.
• The code reference launch_fluent(file_transfer_service=<name_of_the_file_transfer_service>) should be formatted consistently, probably as a code block or inline code.
• The sentence about defining your own file transfer service (“You can define your own…”) feels premature if we’re not showing how to do that in the doc. Unless we’re planning to add an example or guidance for this, we might want to omit that line for now.
• Question: Is it truly the case that the Remote file transfer service is only applicable when running in container mode? If not, we should revise that statement.
• The Remote file transfer section dives straight into gRPC implementation details without first describing why a user would want to use it. I’d recommend briefly framing its purpose or benefit first.
• Similarly, for the Local file transfer service, it would help to explain what this is in practical terms, and why a user might choose it—i.e., “use this if you're running Fluent locally in standalone mode,” etc.
• The examples still contain explicit upload() and download() calls, even where file operations would work seamlessly without them. This could confuse users into thinking those calls are always required. Can we trim or annotate the examples accordingly?
• The large “Examples” headings break the structure awkwardly now that we’re splitting the examples per service. Consider removing or replacing with something more descriptive like “Example: Using the Local File Transfer Service”.
• Finally, naming-wise: file_transfer_service=LocalFileTransferStrategy() and similar is a bit clunky. I’m not sure what the best solution is, but maybe a more user-facing alias could be introduced?

I used Chat GPT to help make some improvements based on the above points and the following code block should be used as a basis. However, it is crucial to proof-read it for inaccuracies as I can see that some things look a bit off the mark (it lacks complete context) while I already corrected some other details.

.. _ref_file_transfer_guide:

File transfer
=============

PyFluent provides a file transfer service that manages how files are uploaded to and downloaded from the Fluent server.  
This service allows file-based API methods like `read_case()` and `write_mesh()` to work seamlessly—even when Fluent is running remotely, in a container, or in a PIM-managed environment.

Depending on how Fluent is launched, different file transfer strategies are available:

1. **Local file transfer service**

   When Fluent is launched in standalone mode on the same machine as the Python client, files can be accessed directly from the local file system. In this case, the local file transfer service is used.

   Use this service when:
   - Fluent is running locally.
   - You want to ensure explicit control over file movement using `upload()` and `download()`.

   Example:

   .. code-block:: python

      >>> import ansys.fluent.core as pyfluent
      >>> from ansys.fluent.core import examples
      >>> from ansys.fluent.core.utils.file_transfer_service import LocalFileTransferStrategy

      >>> mesh_file = examples.download_file("mixing_elbow.msh.h5", "pyfluent/mixing_elbow")

      >>> session = pyfluent.launch_fluent(mode=pyfluent.FluentMode.MESHING, 
      ...                                   file_transfer_service=LocalFileTransferStrategy())
      >>> session.upload(file_name=mesh_file, remote_file_name="elbow.msh.h5")
      >>> session.meshing.File.ReadMesh(FileName="elbow.msh.h5")
      >>> session.meshing.File.WriteMesh(FileName="write_elbow.msh.h5")
      >>> session.download(file_name="write_elbow.msh.h5", local_directory="<local_path>")

2. **Remote file transfer service**

   When Fluent runs in a Docker container or another remote environment, files cannot be shared directly between client and server.  
   The remote file transfer service uses a gRPC-based mechanism to manage transfers.

   Use this service when:
   - Fluent is running in container mode or remotely.
   - You need to transfer files explicitly between environments.

   Example:

   .. code-block:: python

      >>> import ansys.fluent.core as pyfluent
      >>> from ansys.fluent.core import examples
      >>> from ansys.fluent.core.utils.file_transfer_service import RemoteFileTransferStrategy

      >>> case_file = examples.download_file("mixing_elbow.cas.h5", "pyfluent/mixing_elbow")

      >>> session = pyfluent.launch_fluent(file_transfer_service=RemoteFileTransferStrategy())
      >>> session.upload(file_name=case_file, remote_file_name="elbow.cas.h5")
      >>> session.file.read_case(file_name="elbow.cas.h5")
      >>> session.file.write_case(file_name="write_elbow.cas.h5")
      >>> session.download(file_name="write_elbow.cas.h5", local_directory="<local_path>")

3. **PIM file transfer service**

   When launching Fluent through the Product Instance Management (PIM), file transfer is fully automated.  
   You don’t need to call `upload()` or `download()`—files are transferred transparently when you use file-based API methods.

   Use this service when:
   - You launch Fluent using PIM.
   - You want seamless file transfers without needing to manage them directly.

   Example:

   .. code-block:: python

      >>> import ansys.fluent.core as pyfluent
      >>> from ansys.fluent.core import examples

      >>> case_file = examples.download_file("mixing_elbow.cas.h5", "pyfluent/mixing_elbow")

      >>> session = pyfluent.launch_fluent()
      >>> session.file.read_case(file_name=case_file)
      >>> session.file.write_case(file_name="write_mixing_elbow.cas.h5")

Defining your own file transfer service
---------------------------------------

Advanced users can define a custom file transfer strategy and use it when launching Fluent:

.. code-block:: python

   >>> pyfluent.launch_fluent(file_transfer_service=<your_custom_strategy>)

(Instructions for creating a custom strategy are beyond the scope of this guide.)

@seanpearsonuk Done. Thank you.

[hpohekar]

@seanpearsonuk This PR is ready.

[seanpearsonuk]

This looks like a distinct upgrade. Thanks.

[prmukherj]

Looks much more readable and clear now.