Doc: PySimAI examples section (#56)

Co-authored-by: Revathyvenugopal162 <[email protected]>
Co-authored-by: Marc Planelles <[email protected]>
Co-authored-by: Revathy Venugopal <[email protected]>
Co-authored-by: ibazian <[email protected]>

doc/source/conf.py

@@ -36,8 +36,10 @@
 #
 import os
 from datetime import datetime
+from pathlib import Path
 
 from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_black
+from sphinx_gallery.sorting import FileNameSortKey
 
 from ansys.simai.core import __version__
 
@@ -49,6 +51,9 @@
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
 cname = os.getenv("DOCUMENTATION_CNAME", "simai.docs.pyansys.com")
 
+SOURCE_PATH = Path(__file__).parent.resolve().absolute()
+ANSYS_SIMAI_THUMBNAIL = str(os.path.join(SOURCE_PATH, "_static", "ansys_simai.png"))
+
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -60,8 +65,22 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "sphinxcontrib.autodoc_pydantic",
+    "sphinx_gallery.gen_gallery",
 ]
-
+# Sphinx Gallery Options
+
+sphinx_gallery_conf = {
+    # default png file for thumbnails
+    "default_thumb_file": ANSYS_SIMAI_THUMBNAIL,
+    # path to your examples scripts
+    "examples_dirs": ["examples"],
+    # path where to save gallery generated examples
+    "gallery_dirs": ["_examples"],
+    # Remove the "Download all examples" button from the top level gallery
+    "download_all_examples": False,
+    # Sort gallery example by file name instead of number of lines (default)
+    "within_subsection_order": FileNameSortKey,
+}
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
 }
@@ -113,6 +132,8 @@
 html_favicon = ansys_favicon
 html_static_path = ["_static"]
 
+suppress_warnings = ["config.cache"]
+
 html_context = {
     "github_user": "ansys",
     "github_repo": "pysimai",

doc/source/examples/00-model_configuration_reuse.py

@@ -0,0 +1,64 @@
+""".. _ref_model_configuration_reuse:
+
+Model configuration reuse
+=========================
+
+This example demonstrates how to retrieve the latest model configuration
+of a project and use it to launch a model build in another project.
+
+"""
+
+###############################################################################
+# Import necessary libraries
+# --------------------------
+
+import ansys.simai.core as asc
+
+simai = asc.from_config()
+
+###############################################################################
+# Create a project and allocate training data
+# -------------------------------------------
+# Define the project name.
+new_project_name = "new-project"
+
+###############################################################################
+# Create the project.
+new_project = simai.projects.create(new_project_name)
+
+###############################################################################
+# Set the names of the data samples to be associated with the created project.
+training_samples_name = [
+    "TrainingData_001",
+    "TrainingData_002",
+    "TrainingData_003",
+    "TrainingData_004",
+]
+
+###############################################################################
+# Retrieve the desired training data samples and associate them with
+# the new project.
+for td_name in training_samples_name:
+    filt = {"name": td_name}
+    td = simai.training_data.list(filters=filt)
+    td[0].add_to_project(new_project)
+
+###############################################################################
+# Select a model configuration and associate it with the newly created project
+# ----------------------------------------------------------------------------
+# Retrieve the model configuration from another project that you wish to reuse.
+old_project = "old-ps"
+my_project = simai.projects.get(name=old_project)
+
+last_build_config = my_project.last_model_configuration
+
+###############################################################################
+# If the new project meets the requirements for training, associate
+# the project's ID with the configuration and launch a model build.
+if new_project.is_trainable():
+    # Assign the new project's ID to the configuration to transfer the
+    # configuration from the old project to the new one
+    last_build_config.project_id = new_project.id
+
+    # Launch a model build for the new project
+    new_model = simai.models.build(last_build_config)

doc/source/examples/01-model_recomputation.py

@@ -0,0 +1,46 @@
+"""
+.. _ref_model_recomputation:
+
+Model recomputation
+===================
+
+This example demonstrates how to relaunch a model build using the latest
+model configuration in a same project.
+
+"""
+
+###############################################################################
+# Import necessary libraries
+# --------------------------
+
+import ansys.simai.core as asc
+
+simai = asc.from_config()
+
+###############################################################################
+# Get the project from the server
+# -------------------------------
+
+my_project = simai.projects.get(name="old-ps")
+
+###############################################################################
+# Get the model configuration
+# ---------------------------
+# Get the latest model configuration of the project.
+
+last_build_config = my_project.last_model_configuration
+
+###############################################################################
+# Verify the project requirements
+# -------------------------------
+# Verify that the project meets the requirements for training (model building).
+
+is_trainable_check = my_project.is_trainable()
+
+###############################################################################
+# If the project met the requirements, launch a model build.
+# Otherwise, print the reasons the project does not meet the requirements.
+if is_trainable_check:
+    new_model = simai.models.build(last_build_config)
+else:
+    print(is_trainable_check.reason)

doc/source/examples/02-subset_assignment.py

@@ -0,0 +1,50 @@
+"""
+.. _ref_subset_assignment:
+
+Subset assignment
+=================
+
+This example demonstrates how to assign a subset
+to a training data.
+
+"""
+
+###############################################################################
+# Import necessary libraries
+# --------------------------
+
+import ansys.simai.core as asc
+
+simai = asc.from_config()
+
+###############################################################################
+# Select a training data
+# ----------------------
+# Example of a training_data_id associated with a project_id.
+
+training_data_id = "k4z77qzq"
+project_id = "k9756vw0"
+
+###############################################################################
+# Get subset assignment
+# ---------------------
+# Get and print the current subset assigned for this training_data_id.
+
+current_subset = simai.training_data.get(id=training_data_id).get_subset(project=project_id)
+print(current_subset)
+
+###############################################################################
+# Assign a new subset (two options)
+# ---------------------------------
+# Manually assign a new subset to the training data.
+
+simai.training_data.get(id=training_data_id).assign_subset(project=project_id, subset="Test")
+
+###############################################################################
+# Alternatively, use SubsetEnum to assign a valid enum value to the training data.
+
+from ansys.simai.core.data.types import SubsetEnum
+
+simai.training_data.get(id=training_data_id).assign_subset(
+    project=project_id, subset=SubsetEnum.TEST
+)

doc/source/examples/03-list_based_subset_assignment.py

@@ -0,0 +1,47 @@
+"""
+.. _ref_list_based_subset_assignment:
+
+List-based subset assignment
+============================
+
+This example demonstrates how to distribute your dataset between Test
+and Training subsets using lists.
+
+"""
+
+###############################################################################
+# Import necessary libraries
+# --------------------------
+
+import ansys.simai.core
+
+###############################################################################
+# Create lists
+# ------------
+# List the data to be used for the test set.
+
+# CAUTION:
+# All training data that are not included into the following list will be
+# assigned the training subset
+TEST_LIST = ["My_td_1", "My_td_2"]
+
+###############################################################################
+# Connect to the platform
+# ------------------------
+# Connect to the SimAI platform. Refer to the :ref:`anchor-credentials`
+# section of the documentation to adapt the connection type.
+
+simai = ansys.simai.core.SimAIClient(organization="My_organization_name")
+project = simai.projects.get(name="My_project_name")
+
+###############################################################################
+# Assign subsets
+# --------------
+# Assign a subset to each dataset (list) you created.
+
+td_list = project.data
+for td in td_list:
+    if td.name in TEST_LIST:
+        td.assign_subset(project, "Test")
+    else:
+        td.assign_subset(project, "Training")

doc/source/examples/README.txt

@@ -0,0 +1,8 @@
+.. _gallery:
+
+========
+Examples
+========
+
+This section provides a collection of practical script examples illustrating SimAI functionalities and use cases.
+They serve as a reference guide for users to implement similar solutions in their projects.

doc/source/index.rst

@@ -6,6 +6,7 @@
 
    user_guide
    api_reference
+   _examples/index
 
 PySimAI documentation
 =====================

doc/source/user_guide/configuration.rst

@@ -39,6 +39,8 @@ class:
   :field-list-validators: False
 
 
+.. _anchor-credentials:
+
 Credentials
 -----------