doc: Ansys standards (#15)

* First-round edits to RST files * Resolve tagging issues causing doc building check to fail * Resolve more tagging issues causing doc building check to fail * Try again to resolve method role * Incorporate review comments * Commit edits to PY files through post_processing.py. * Resolve Vale issue * Address issues that prevent doc building * Resolve issues * Edits to the remaining PY files in the data directory * Fix format error * Edits to files in utils folder * Edits of all file types based on skimming rendered doc * Fix type * Fix doc format error * Fix indent issue * Apply suggestions from code review Incorporate feedback. Great catches all! Co-authored-by: Revathy Venugopal <[email protected]> Co-authored-by: Marc Planelles <[email protected]> --------- Co-authored-by: Revathy Venugopal <[email protected]> Co-authored-by: Marc Planelles <[email protected]>
ansys · Jan 12, 2024 · c007955 · c007955
1 parent 7b65411
commit c007955
Show file tree

Hide file tree

Showing 58 changed files with 1,328 additions and 1,211 deletions.
diff --git a/doc/source/api_reference.rst b/doc/source/api_reference.rst
@@ -1,6 +1,6 @@
 .. _api_reference:
 
-API Reference
+API reference
 =============
 
 .. toctree::

diff --git a/doc/source/api_reference/data_types.rst b/doc/source/api_reference/data_types.rst
@@ -1,4 +1,4 @@
-Data Types
+Data types
 ==========
 
 .. automodule:: ansys.simai.core.data.types

diff --git a/doc/source/api_reference/design_of_experiments.rst b/doc/source/api_reference/design_of_experiments.rst
@@ -1,11 +1,12 @@
 .. _design_of_experiments:
 
-Design of Experiments
+Design of experiments
 =====================
 
 .. py:module:: ansys.simai.core.data.design_of_experiments
 
-This collection contain methods allowing to export your Design of Experiments in different formats.
+This module contains methods for exporting design of experiments
+in different formats.
 
 .. autoclass:: DesignOfExperimentsCollection()
     :members:
diff --git a/doc/source/api_reference/geometries.rst b/doc/source/api_reference/geometries.rst
@@ -5,18 +5,20 @@ Geometries
 
 .. py:module:: ansys.simai.core.data.geometries
 
-Geometries are the core of *SimAI Deep Learning powered predictions*.
-A geometry is a 3D model and associated metadata managed by the SimAI platform.
+Geometries are the core of *SimAI deep learning-powered predictions*.
+A geometry is a 3D model and the associated metadata managed by the SimAI platform.
 
 .. _geometry_format:
 
 File format
 -----------
 
 The input format for your workspace is described by the model manifest.
-You can access that information for a specific workspace through :attr:`workspace.model.geometry<ansys.simai.core.data.workspaces.ModelManifest.geometry>`
+You use the :attr:`workspace.model.geometry<ansys.simai.core.data.workspaces.ModelManifest.geometry>`
+attribute to access the information for a specific workspace.
 
-If you have a problem converting to the expected format, please contact us for more information at [email protected]
+If you have a problem converting to the expected format, contact the SimAI team
+at `[email protected] <mailto:[email protected]>`_.
 
 Directory
 ---------

diff --git a/doc/source/api_reference/optimizations.rst b/doc/source/api_reference/optimizations.rst
@@ -18,10 +18,10 @@ Model
     :members:
     :inherited-members:
 
-TrialRun
-========
+TrialRuns
+=========
 
-Trial runs are a single step of the optimization process
+Trial runs are a single step of the optimization process.
 
 Directory
 ---------

diff --git a/doc/source/api_reference/post_processings.rst b/doc/source/api_reference/post_processings.rst
@@ -1,7 +1,7 @@
 .. _post_processings:
 
-Post-Processings
-================
+Postprocessings
+===============
 
 .. py:module:: ansys.simai.core.data.post_processings
 
@@ -20,19 +20,22 @@ Model
 
 .. _pp_methods:
 
-Nested Prediction Namespace
+Nested prediction namespace
 ---------------------------
 
 .. autoclass:: PredictionPostProcessings()
     :members:
 
 .. _available_pp:
 
-Available post-processings
+Available postprocessings
 --------------------------
 
-.. note:: Depending on the capabilities of your model, some of these may not be available in your workspace.
-          You can check which ones are available through the :meth:`~ansys.simai.core.data.post_processings.PostProcessingDirectory.info` method
+.. note::
+    Depending on the capabilities of your model, some of these objects may not
+    be available in your workspace. You can use the
+    :meth:`~ansys.simai.core.data.post_processings.PostProcessingDirectory.info` method
+    to see which ones are available.
 
 .. autoclass:: GlobalCoefficients()
     :members:

diff --git a/doc/source/api_reference/predictions.rst b/doc/source/api_reference/predictions.rst
@@ -1,27 +1,24 @@
+.. _predictions:
+
 Predictions
 ===========
 
 .. py:module:: ansys.simai.core.data.predictions
 
-The Prediction module is in charge of running the *SimAI-powered
-predictions* on the :py:class:`Geometries<ansys.simai.core.data.geometries.Geometry>` you have uploaded.
+The ``Prediction`` module is in charge of running the *SimAI-powered
+predictions* on the :py:class:`geometries<ansys.simai.core.data.geometries.Geometry>`
+that you have uploaded.
 
-It represents a numerical prediction with geometry and boundary conditions.
-The arguments to :py:func:`predictions.run()<PredictionDirectory.run>` depend on your model.
+A prediction represents a numerical prediction with geometry and boundary conditions.
+The arguments to the :py:meth:`predictions.run()<PredictionDirectory.run>` method
+depend on your model.
 
 .. code-block:: python
 
     # Run a prediction on a given geometry with the specified velocity.
     velocity = 10.0
     prediction = geometry.run_prediction(Vx=velocity)
 
-.. warning::
-    In order to better describe different physical constraints,
-    the SimAI SDK has been updated to describe boundary conditions with a dict,
-    replacing the previous tuple of 3 numbers.
-    Please make sure to update your existing scripts, for instance from ``(3.4, 0, 0)`` to ``dict(Vx=3.4)``;
-    there is no need to put ``Vy=0`` and ``Vz=0`` anymore if your project has not been trained on those velocities.
-    In method calls, boundary conditions can be passed directly as arguments: ``run_prediction(Vx=3.4)``.
 
 Directory
 ---------

diff --git a/doc/source/api_reference/selections.rst b/doc/source/api_reference/selections.rst
@@ -1,21 +1,20 @@
 .. _selections:
 
 Selections
-===========
+==========
 
-Selections Basics
------------------
+Selection basics
+----------------
 .. py:module:: ansys.simai.core.data.selections
 
-The Selection class allows you to run a large number of operations in parallel,
-by manipulating whole collections of SimAI models
+The :class:`Selection<ansys.simai.core.data.selections.Selection>` class allows you
+to run a large number of operations in parallel by manipulating whole collections of SimAI models
 (:class:`Geometries <ansys.simai.core.data.geometries.Geometry>`,
-:class:`Predictions <ansys.simai.core.data.predictions.Prediction>`,
-:py:class:`Post-Processings <ansys.simai.core.data.post_processings.PostProcessing>`).
+:class:`Predictions <ansys.simai.core.data.predictions.Prediction>`, and
+:py:class:`Post-Processings <ansys.simai.core.data.post_processings.PostProcessing>` instances).
 
-A Selection is created by combining a list of
-:class:`Geometries <ansys.simai.core.data.geometries.Geometry>` with a list of
-:class:`~ansys.simai.core.data.types.BoundaryConditions`.
+You create a selection by combining a list of :class:`Geometry <ansys.simai.core.data.geometries.Geometry>`
+instances with a list of :class:`~ansys.simai.core.data.types.BoundaryConditions` instances:
 
 .. code-block:: python
 
@@ -26,12 +25,13 @@ A Selection is created by combining a list of
    selection = Selection(geometries, boundary_conditions)
 
 
-The resulting selection contains all possible combinations between
-the geometries and boundary conditions. Each of those combinations is a
-:class:`~ansys.simai.core.data.selections.Point`, which can be viewed as a potential
-:class:`~ansys.simai.core.data.predictions.Prediction`.
+The resulting selection contains all possible combinations between the geometries and
+boundary conditions. Each of those combinations is a :class:`~ansys.simai.core.data.selections.Point`
+instance, which can be viewed as a potential :class:`~ansys.simai.core.data.predictions.Prediction`
+instance.
 
-At first all predictions may not all exist, they can be run with the :func:`~Selection.run_predictions` method:
+At first, all predictions may not exist. However, you can use the :meth:`~Selection.run_predictions`
+method to run them:
 
 .. code-block:: python
 
@@ -41,10 +41,11 @@ At first all predictions may not all exist, they can be run with the :func:`~Sel
    all_predictions = selection.predictions
 
 
-Selections API Reference
+Selection API reference
 ------------------------
 
-In essence a :class:`~ansys.simai.core.data.selections.Selection` is a collection of :class:`points <ansys.simai.core.data.selections.Point>`.
+In essence, a :class:`~ansys.simai.core.data.selections.Selection` instance is a
+collection of :class:`points <ansys.simai.core.data.selections.Point>` instances.
 
 .. autoclass:: Point()
     :members:
@@ -56,12 +57,13 @@ In essence a :class:`~ansys.simai.core.data.selections.Selection` is a collectio
     :inherited-members:
 
 
-Post-processing Basics
+Postprocessing basics
 ----------------------
 
-The :attr:`~Selection.post` namespace allows you to run and access all post-processings for existing predictions.
-Please see :py:class:`~ansys.simai.core.data.selection_post_processings.SelectionPostProcessingsMethods`
-for available post-processings.
+The :attr:`~Selection.post` namespace allows you to run and access all postprocessings
+for existing predictions. For available postprocessings, see the
+:py:class:`~ansys.simai.core.data.selection_post_processings.SelectionPostProcessingsMethods`
+class.
 
 .. code-block:: python
 
@@ -70,19 +72,20 @@ for available post-processings.
     coeffs.data  # is a list of results of each post-processings.
 
 
-Results for exportable post-processings
+You can use the :meth:`~ansys.simai.core.data.lists.ExportablePPList.export()`
+method to export results in batch for exportable postprocessings
 (:py:class:`~ansys.simai.core.data.post_processings.GlobalCoefficients`
-and :py:class:`~ansys.simai.core.data.post_processings.SurfaceEvol`)
-can be exported in batch with the :func:`~ansys.simai.core.data.lists.ExportablePPList.export()` method:
+and :py:class:`~ansys.simai.core.data.post_processings.SurfaceEvol` instances):
 
 .. code-block:: python
 
     selection.post.surface_evol(axis="x", delta=13.5).export("xlsx").download(
         "/path/to/file.xlsx"
     )
 
-Please note that the ``csv`` export generates a zip archive containing multiple csv files.
-They can be read directly with python by using zipfile:
+Note that a CSV export generates a ZIP file containing multiple CSV files.
+You can read them directly using Python's `zipfile<https://docs.python.org/3/library/zipfile.html>`
+module:
 
 .. code-block:: python
 
@@ -101,15 +104,15 @@ They can be read directly with python by using zipfile:
         df_geom = pd.read_csv(archive.open("Geometries.csv"))
 
 
-Binary post-processings results can be downloaded by looping on the list, for instance:
+You can download binary postprocessings results by looping on the list:
 
 .. code-block:: python
 
     for vtu in selection.post.volume_vtu():
         vtu.data.download(f"/path/to/vtu_{vtu.id}")
 
 
-Post-processing API Reference
+Postprocessing API reference
 -----------------------------
 
 .. py:module:: ansys.simai.core.data.selection_post_processings

diff --git a/doc/source/api_reference/training_data.rst b/doc/source/api_reference/training_data.rst
@@ -1,12 +1,13 @@
 .. _training_data:
 
-Training Data
-=============
+TrainingData
+============
 
 .. py:module:: ansys.simai.core.data.training_data
 
-A TrainingData is a collection of :class:`parts<ansys.simai.core.data.training_data_parts.TrainingDataPart>` representing
-a prediction that can then be used as input for the training of models.
+A :class:`TrainingData<ansys.simai.core.data.training_data.TrainingData>` instance is a
+collection of :class:`TrainingDataPart<ansys.simai.core.data.training_data_parts.TrainingDataPart>`
+instances representing a prediction that can be used as input for the training of models.
 
 Directory
 ---------

diff --git a/doc/source/api_reference/training_data_parts.rst b/doc/source/api_reference/training_data_parts.rst
@@ -1,11 +1,13 @@
 .. _training_data_parts:
 
-Training Data Part
-==================
+TrainingDataParts
+=================
 
 .. py:module:: ansys.simai.core.data.training_data_parts
 
-A TrainingDataPart is a singular file, part of a :class:`~ansys.simai.core.data.training_data.TrainingData`.
+A :class:`TrainingDataPart<ansys.simai.core.data.training_data_parts.TrainingDataPart>` instance
+is a singular file that is part of a :class:`~ansys.simai.core.data.training_data.TrainingData`
+instance.
 
 Directory
 ---------

diff --git a/doc/source/api_reference/workspaces.rst b/doc/source/api_reference/workspaces.rst
@@ -5,11 +5,11 @@ Workspaces
 
 .. py:module:: ansys.simai.core.data.workspaces
 
-Workspaces are a set of specific geometries, predictions and post-processings.
+Workspaces are a set of specific geometries, predictions, and postprocessings.
 Each workspace uses a specific kernel.
 
-To set which workspace the client is configured for, please refer to
-:meth:`SimAIClient.set_current_workspace() method<ansys.simai.core.client.SimAIClient.set_current_workspace>`
+You use the :meth:`SimAIClient.set_current_workspace()<ansys.simai.core.client.SimAIClient.set_current_workspace>`
+method to set the workspace that the client is configured for.
 
 Directory
 ---------