feat: parameters refurbished (#1647)

Co-authored-by: pyansys-ci-bot <[email protected]>
Co-authored-by: Roberto Pastor Muela <[email protected]>
Co-authored-by: Kathy Pippert <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

doc/changelog.d/1647.added.md

@@ -0,0 +1 @@
+parameters refurbished

doc/source/conf.py

@@ -303,6 +303,7 @@ def intersphinx_pyansys_geometry(switcher_version: str):
     "examples/03_modeling/design_tree": "_static/thumbnails/design_tree.png",
     "examples/03_modeling/service_colors": "_static/thumbnails/service_colors.png",
     "examples/03_modeling/surface_bodies": "_static/thumbnails/quarter_sphere.png",
+    "examples/03_modeling/design_parameters": "_static/thumbnails/block_with_parameters.png",
     "examples/03_modeling/chamfer": "_static/thumbnails/chamfer.png",
     "examples/04_applied/01_naca_airfoils": "_static/thumbnails/naca_airfoils.png",
     "examples/04_applied/02_naca_fluent": "_static/thumbnails/naca_fluent.png",

doc/source/examples.rst

@@ -49,6 +49,7 @@ These examples demonstrate service-based modeling operations.
     examples/03_modeling/design_tree.mystnb
     examples/03_modeling/service_colors.mystnb
     examples/03_modeling/surface_bodies.mystnb
+    examples/03_modeling/design_parameters.mystnb
     examples/03_modeling/chamfer.mystnb
 
 Applied examples

doc/source/examples/03_modeling/design_parameters.mystnb

@@ -0,0 +1,145 @@
+---
+jupytext:
+  text_representation:
+    extension: .mystnb
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.16.4
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+---
+
+# Modeling: Using design parameters
+
+You can read and update parameters that are part of the design.
+The simple design in this example has two associated parameters.
+
++++
+
+## Perform required imports
+
+```{code-cell} ipython3
+import os
+import requests
+from ansys.geometry.core import launch_modeler
+from ansys.geometry.core.modeler import *
+from ansys.geometry.core.parameters import *
+```
+
+The file for this example is in the integration tests folder and can be downloaded.
+
++++
+
+## Download the example file
+
++++
+
+Download the file for this example from the integration tests folder in the PyAnsys Geometry repository.
+
+```{code-cell} ipython3
+import requests
+
+def download_file(url, filename):
+    """Download a file from a URL and save it to a local file."""
+    response = requests.get(url)
+    response.raise_for_status()  # Check if the request was successful
+    with open(filename, 'wb') as file:
+        file.write(response.content)
+
+# URL of the file to download
+url = "https://github.com/ansys/pyansys-geometry/blob/main/tests/integration/files/blockswithparameters.dsco"
+
+# Local path to save the file to
+file_name = "blockswithparameters.dsco"
+current_path = os.getcwd()
+file_path = os.path.join(current_path, file_name)
+# Download the file
+download_file(url, file_path)
+print("File is downloaded to " + file_path)
+```
+
+## Import a design with parameters
+
++++
+
+Import the model using the ``open_file()`` method of the modeler.
+
+```{code-cell} ipython3
+# Create a modeler object
+modeler = launch_modeler()
+design = modeler.open_file(file_path)
+design.plot()
+```
+
+## Read existing parameters of the design
+
+You can get all the parameters of the design as a list of parameters. Because this example has two parameters, you see two items in the list.
+
+```{code-cell} ipython3
+my_parameters = design.get_all_parameters()
+print(len(my_parameters))
+```
+
+A parameter object has a name, value, and unit.
+
+```{code-cell} ipython3
+print(my_parameters[0].name)
+print(my_parameters[0].dimension_value)
+print(my_parameters[0].dimension_type)
+
+print(my_parameters[1].name)
+print(my_parameters[1].dimension_value)
+print(my_parameters[1].dimension_type)
+```
+
+Parameter values are returned in the default unit for each dimension type. Since default length unit is meter and default area unit is meter square, the value is returned in metersquare.
+
++++
+
+## Edit a parameter value
+
+You can edit the parameter's name or value by simply setting these fields.
+Set the second parameter (p2 value to 350 mm).
+
+```{code-cell} ipython3
+parameter1 = my_parameters[1]
+parameter1.dimension_value = 0.000440
+response = design.set_parameter(parameter1)
+print(response)
+print(my_parameters[0].dimension_value)
+print(my_parameters[1].dimension_value)
+```
+
+After a successful parameter update, the design in the backend might have been updated. Therefore, you must refresh the design on the client.
+
+```{code-cell} ipython3
+design = modeler.read_existing_design()
+design.plot()
+```
+
+The ``set_parameter()`` method returns a ``Success`` status message if the parameter is updated or a "FAILURE" status message if the update fails. If the ``p2`` parameter depends on the ``p1`` parameter, updating the ``p1`` parameter might also change the ``p2`` parameter. In such cases, the method returns ``CONSTRAINED_PARAMETERS``, which indicates other parameters were also updated.
+
+```{code-cell} ipython3
+parameter1 = my_parameters[0]
+parameter1.dimension_value = 0.000250
+response = design.set_parameter(parameter1)
+print(response)
+```
+
+To get the updated list, query the parameters once again.
+
+```{code-cell} ipython3
+my_parameters = design.get_all_parameters()
+print(my_parameters[0].dimension_value)
+print(my_parameters[1].dimension_value)
+```
+
+## Close the modeler
+
+Close the modeler to free up resources and release the connection.
+
+```{code-cell} ipython3
+modeler.close()
+```

src/ansys/geometry/core/designer/design.py

@@ -33,6 +33,8 @@
 from ansys.api.dbu.v0.dbumodels_pb2 import EntityIdentifier, PartExportFormat
 from ansys.api.dbu.v0.designs_pb2 import InsertRequest, NewRequest, SaveAsRequest
 from ansys.api.dbu.v0.designs_pb2_grpc import DesignsStub
+from ansys.api.dbu.v0.drivingdimensions_pb2 import GetAllRequest, UpdateRequest
+from ansys.api.dbu.v0.drivingdimensions_pb2_grpc import DrivingDimensionsStub
 from ansys.api.geometry.v0.commands_pb2 import (
     AssignMidSurfaceOffsetTypeRequest,
     AssignMidSurfaceThicknessRequest,
@@ -74,6 +76,7 @@
 from ansys.geometry.core.misc.checks import ensure_design_is_active, min_backend_version
 from ansys.geometry.core.misc.measurements import DEFAULT_UNITS, Distance
 from ansys.geometry.core.modeler import Modeler
+from ansys.geometry.core.parameters.parameter import Parameter, ParameterUpdateStatus
 from ansys.geometry.core.typing import RealSequence
 
 
@@ -125,6 +128,7 @@ def __init__(self, name: str, modeler: Modeler, read_existing_design: bool = Fal
         self._materials_stub = MaterialsStub(self._grpc_client.channel)
         self._named_selections_stub = NamedSelectionsStub(self._grpc_client.channel)
         self._parts_stub = PartsStub(self._grpc_client.channel)
+        self._parameters_stub = DrivingDimensionsStub(self._grpc_client.channel)
 
         # Initialize needed instance variables
         self._materials = []
@@ -166,6 +170,11 @@ def beam_profiles(self) -> list[BeamProfile]:
         """List of beam profile available for the design."""
         return list(self._beam_profiles.values())
 
+    @property
+    def parameters(self) -> list[Parameter]:
+        """List of parameters available for the design."""
+        return self.get_all_parameters()
+
     @property
     def is_active(self) -> bool:
         """Whether the design is currently active."""
@@ -679,6 +688,45 @@ def add_beam_circular_profile(
 
         return self._beam_profiles[profile.name]
 
+    @protect_grpc
+    @min_backend_version(25, 1, 0)
+    def get_all_parameters(self) -> list[Parameter]:
+        """Get parameters for the design.
+
+        Returns
+        -------
+        list[Parameter]
+            List of parameters for the design.
+        """
+        response = self._parameters_stub.GetAll(GetAllRequest())
+        return [Parameter._from_proto(dimension) for dimension in response.driving_dimensions]
+
+    @protect_grpc
+    @check_input_types
+    @min_backend_version(25, 1, 0)
+    def set_parameter(self, dimension: Parameter) -> ParameterUpdateStatus:
+        """Set or update a parameter of the design.
+
+        Parameters
+        ----------
+        dimension : Parameter
+            Parameter to set.
+
+        Returns
+        -------
+        ParameterUpdateStatus
+            Status of the update operation.
+        """
+        request = UpdateRequest(driving_dimension=Parameter._to_proto(dimension))
+        response = self._parameters_stub.UpdateParameter(request)
+        status = response.status
+
+        # Update the design in place. This method is computationally expensive,
+        # consider finding a more efficient approach.
+        self._update_design_inplace()
+
+        return ParameterUpdateStatus._from_update_status(status)
+
     @protect_grpc
     @check_input_types
     @ensure_design_is_active

src/ansys/geometry/core/modeler.py

@@ -243,6 +243,10 @@ def close(self, close_designs: bool = True) -> None:
         # Close the client
         self.client.close()
 
+    def close_all_designs(self) -> None:
+        """Close all existing designs in the modeler workspace."""
+        [design.close() for design in self._designs.values()]
+
     def exit(self, close_designs: bool = True) -> None:
         """Access the client's close method.
 

src/ansys/geometry/core/parameters/__init__.py

@@ -0,0 +1,24 @@
+# Copyright (C) 2023 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""PyAnsys Geometry parameters subpackage."""
+
+from ansys.geometry.core.parameters.parameter import Parameter, ParameterType