Add 3d microstructure simulation API (#283)

Co-authored-by: Kathy Pippert <[email protected]>

.github/workflows/ci_cd.yml

@@ -18,7 +18,7 @@ env:
   DOCUMENTATION_CNAME: "additive.docs.pyansys.com"
   LIBRARY_NAME: "ansys-additive-core"
   # NOTE: The server needs to stay in a private registry.
-  ANSYS_PRODUCT_IMAGE: "ghcr.io/ansys-internal/additive:24.2.0-alpha1"
+  ANSYS_PRODUCT_IMAGE: "ghcr.io/ansys-internal/additive:latest"
   ANSYS_PRODUCT_CONTAINER: "ansys-additive-container"
 
 concurrency:

.pre-commit-config.yaml

@@ -64,9 +64,9 @@ repos:
         args: [-vv, -m, -p, -S, -s, -n, --fail-under=100]
         files: src
 
-  - repo: https://github.com/ansys/pre-commit-hooks
-    rev: v0.2.9
-    hooks:
-      - id: add-license-headers
-        args:
-          - --start_year=2023
+  # - repo: https://github.com/ansys/pre-commit-hooks
+  #   rev: v0.2.9
+  #   hooks:
+  #     - id: add-license-headers
+  #       args:
+  #         - --start_year=2023

examples/02_additive_microstructure.py → examples/02_additive_2d_microstructure.py

@@ -20,12 +20,13 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 """
-Microstructure analysis
-#######################
+2D Microstructure analysis
+##########################
 
 This example shows how to use PyAdditive to determine
-the microstructure for a sample coupon with given material
-and machine parameters.
+the two-dimensional microstructure in the XY, XZ, and YZ
+planes for a sample coupon with given material and
+machine parameters.
 
 Units are SI (m, kg, s, K) unless otherwise noted.
 """

examples/12_additive_3d_microstructure_beta.py

@@ -0,0 +1,149 @@
+# Copyright (C) 2023 - 2024 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.
+"""
+3D Microstructure analysis (BETA)
+#################################
+
+.. warning::
+    Beta Features Disclaimer
+
+    * This is beta documentation for one or more beta software features.
+    * Beta features are considered unreleased and have not been fully tested nor
+      fully validated. The results are not guaranteed by Ansys, Inc. (Ansys) to be
+      correct. You assume the risk of using beta features.
+    * At its discretion, Ansys may release, change, or withdraw beta features
+      in future revisions.
+    * Beta features are not subject to the Ansys Class 3 error reporting system.
+      Ansys makes no commitment to resolve defects reported against beta features;
+      however, your feedback will help us improve the quality of the product.
+    * Ansys does not guarantee that database and/or input files used with beta
+      features will run successfully from version to version of the software, nor
+      with the final released version of the features. You may need to modify the
+      database and/or input files before running them on other versions.
+    * Documentation for beta features is called beta documentation, and it may
+      not be written to the same standard as documentation for released features.
+      Beta documentation may not be complete at the time of product release.
+      At its discretion, Ansys may add, change, or delete beta documentation
+      at any time.
+
+This example shows how to use PyAdditive to determine
+the three-dimensional microstructure for a sample coupon
+with given material and machine parameters.
+
+Units are SI (m, kg, s, K) unless otherwise noted.
+"""
+###############################################################################
+# Perform required import and connect
+# -----------------------------------
+# Perform the required import and connect to the Additive service.
+
+import pyvista as pv
+
+from ansys.additive.core import Additive, AdditiveMachine, Microstructure3DInput, SimulationError
+
+additive = Additive()
+
+###############################################################################
+# Select material
+# ---------------
+# Select a material. You can use the :meth:`~Additive.materials_list` method to
+# obtain a list of available materials.
+
+print("Available material names: {}".format(additive.materials_list()))
+
+###############################################################################
+# You can obtain the parameters for a single material by passing a name
+# from the materials list to the :meth:`~Additive.material` method.
+
+material = additive.material("17-4PH")
+
+###############################################################################
+# Specify machine parameters
+# --------------------------
+# Specify machine parameters by first creating an :class:`AdditiveMachine` object
+# and then assigning the desired values. All values are in SI units (m, kg, s, K)
+# unless otherwise noted.
+
+machine = AdditiveMachine()
+
+# Show available parameters
+print(machine)
+
+###############################################################################
+# Set laser power and scan speed
+# ------------------------------
+# Set the laser power and scan speed.
+
+machine.scan_speed = 1  # m/s
+machine.laser_power = 500  # W
+
+###############################################################################
+# Specify inputs for 3D microstructure simulation
+# ------------------------------------------------
+# Specify microstructure inputs.
+input = Microstructure3DInput(
+    machine=machine,
+    material=material,
+    id="micro-3d",
+    sample_size_x=0.0001,  # in meters (.1 mm)
+    sample_size_y=0.0001,
+    sample_size_z=0.0001,
+)
+
+###############################################################################
+# Run simulation
+# --------------
+# Use the :meth:`~Additive.simulate` method of the ``additive`` object to run the simulation.
+# The returned object is either a :class:`Microstructure3DSummary` object or a
+# :class:`SimulationError` object.
+
+summary = additive.simulate(input)
+if isinstance(summary, SimulationError):
+    raise Exception(summary.message)
+
+
+###############################################################################
+# Plot 3D grain visualization
+# ---------------------------
+# The ``summary`` object includes a VTK file describing the 3D grain structure.
+# The VTK file contains scalar data sets ``GrainNumber``, ``Phi0``,
+# ``Phi1``, ``Phi2``, and ``Temperatures``.
+
+# Plot the Phi0 data of the 3D grain structure
+cmap = "coolwarm"
+ms3d = pv.read(summary.grain_3d_vtk)
+ms3d.plot(scalars="Phi0", cmap=cmap)
+
+# Add a cut plane to the plot
+plotter = pv.Plotter()
+plotter.add_mesh_clip_plane(ms3d, scalars="Phi0", cmap=cmap)
+plotter.show()
+
+###############################################################################
+# Print average grain sizes
+# -------------------------
+# The ``summary`` object includes the average grain sizes in the XY, XZ, and YZ
+# planes.
+
+print("Average grain size in XY plane: {} µm".format(summary.xy_average_grain_size))
+print("Average grain size in XZ plane: {} µm".format(summary.xz_average_grain_size))
+print("Average grain size in YZ plane: {} µm".format(summary.yz_average_grain_size))

pyproject.toml

@@ -25,7 +25,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "ansys-api-additive==1.6.5",
+    "ansys-api-additive==1.6.7",
     "ansys-platform-instancemanagement>=1.1.1",
     "dill>=0.3.7",
     "google-api-python-client>=1.7.11",

src/ansys/additive/core/__init__.py

@@ -60,6 +60,7 @@
     MicrostructureInput,
     MicrostructureSummary,
 )
+from ansys.additive.core.microstructure_3d import Microstructure3DInput, Microstructure3DSummary
 from ansys.additive.core.porosity import PorosityInput, PorositySummary
 from ansys.additive.core.simulation import SimulationError, SimulationStatus, SimulationType
 from ansys.additive.core.single_bead import (

src/ansys/additive/core/additive.py

@@ -43,6 +43,7 @@
 from ansys.additive.core.material import AdditiveMaterial
 from ansys.additive.core.material_tuning import MaterialTuningInput, MaterialTuningSummary
 from ansys.additive.core.microstructure import MicrostructureInput, MicrostructureSummary
+from ansys.additive.core.microstructure_3d import Microstructure3DInput, Microstructure3DSummary
 import ansys.additive.core.misc as misc
 from ansys.additive.core.porosity import PorosityInput, PorositySummary
 from ansys.additive.core.progress_logger import ProgressLogger
@@ -224,32 +225,40 @@ def about(self) -> None:
 
     def simulate(
         self,
-        inputs: SingleBeadInput | PorosityInput | MicrostructureInput | ThermalHistoryInput | list,
+        inputs: (
+            SingleBeadInput
+            | PorosityInput
+            | MicrostructureInput
+            | ThermalHistoryInput
+            | Microstructure3DInput
+            | list
+        ),
     ) -> (
         SingleBeadSummary
         | PorositySummary
         | MicrostructureSummary
         | ThermalHistorySummary
+        | Microstructure3DSummary
         | SimulationError
         | list
     ):
         """Execute additive simulations.
 
         Parameters
         ----------
-        inputs: SingleBeadInput, PorosityInput, MicrostructureInput, ThermalHistoryInput, list
+        inputs: SingleBeadInput, PorosityInput, MicrostructureInput, ThermalHistoryInput,
+        Microstructure3DInput, list
             Parameters to use for simulations. A list of inputs may be provided to execute multiple
             simulations.
 
         Returns
         -------
-        SingleBeadSummary, PorositySummary, MicrostructureSummary, ThermalHistorySummary, SimulationError,
-        list
+        SingleBeadSummary, PorositySummary, MicrostructureSummary, ThermalHistorySummary,
+        Microstructure3DSummary, SimulationError, list
             One or more summaries of simulation results. If a list of inputs is provided, a
             list is returned.
         """
         if type(inputs) is not list:
-            print("Single input")
             return self._simulate(inputs, self._servers[0], show_progress=True)
         else:
             self._validate_inputs(inputs)
@@ -287,15 +296,22 @@ def simulate(
 
     def _simulate(
         self,
-        input: SingleBeadInput | PorosityInput | MicrostructureInput | ThermalHistoryInput,
+        input: (
+            SingleBeadInput
+            | PorosityInput
+            | MicrostructureInput
+            | ThermalHistoryInput
+            | Microstructure3DInput
+        ),
         server: ServerConnection,
         show_progress: bool = False,
     ):
         """Execute a single simulation.
 
         Parameters
         ----------
-        input: SingleBeadInput, PorosityInput, MicrostructureInput, ThermalHistoryInput
+        input: SingleBeadInput, PorosityInput, MicrostructureInput, ThermalHistoryInput,
+        Microstructure3DInput
             Parameters to use for simulation.
 
         server: ServerConnection
@@ -307,7 +323,7 @@ def _simulate(
         Returns
         -------
         SingleBeadSummary, PorositySummary, MicrostructureSummary, ThermalHistorySummary,
-        SimulationError
+        Microstructure3DSummary, SimulationError
         """
         logger = None
         if show_progress:
@@ -337,6 +353,10 @@ def _simulate(
                     return MicrostructureSummary(
                         input, response.microstructure_result, self._user_data_path
                     )
+                if response.HasField("microstructure_3d_result"):
+                    return Microstructure3DSummary(
+                        input, response.microstructure_3d_result, self._user_data_path
+                    )
         except Exception as e:
             return SimulationError(input, str(e))