DOCS: Update modeling setup examples (#186)

* Update Modeling Setup Examples

* DOCS: Fix bullet points

---------

Co-authored-by: Samuel Lopez <85613111+Samuelopez-ansys@users.noreply.github.com>
Co-authored-by: Sébastien Morais <146729917+SMoraisAnsys@users.noreply.github.com>

Author: 3 people

examples/01-Modeling-Setup/Configurations.py

@@ -23,41 +23,40 @@
 # any reason, this face position has changed or the object name in the target
 # design has changed, the boundary fails to apply.
 
-# ## Perform required imports
+# ## Preparation
+# Import the required packages
 
+# +
 import os
 import tempfile
+import time
 
 import pyaedt
 from pyaedt.generic.general_methods import generate_unique_name
+# -
 
-# Set constant values
+# Define constants
 
 AEDT_VERSION = "2024.1"
-
-# ## Set non-graphical mode
-
-# You can set ``non_graphical`` either to ``True`` or ``False``.
-
-non_graphical = False
+NG_MODE = False  # Open Electronics UI when the application is launched.
 
 # ## Create temporary directory
 
-temp_dir = tempfile.TemporaryDirectory(suffix="_ansys")
+temp_dir = tempfile.TemporaryDirectory(suffix=".ansys")
 
 # ## Download project
 
 project_full_name = pyaedt.downloads.download_icepak(destination=temp_dir.name)
 
 # ## Open project
-
-# Open the project, and save it to the temporary folder.
+#
+# Open the Icepak project from the project folder.
 
 ipk = pyaedt.Icepak(
     project=project_full_name,
     version=AEDT_VERSION,
     new_desktop=True,
-    non_graphical=non_graphical,
+    non_graphical=NG_MODE,
 )
 ipk.autosave_disable()
 
@@ -99,23 +98,25 @@
     file_name=filename,
     file_path=ipk.working_directory,
     file_format=".step",
-    object_list=[],
-    removed_objects=[],
+    assignment_to_export=[],
+    assignment_to_remove=[],
 )
 
 # ## Export configuration files
 #
 # Export the configuration files. You can optionally disable the export and
 # import sections. Supported formats are json and toml files
 
-conf_file = ipk.configurations.export_config(os.path.join(ipk.working_directory, "config.toml"))
+conf_file = ipk.configurations.export_config(
+    os.path.join(ipk.working_directory, "config.toml")
+)
 ipk.close_project()
 
 # ## Create project
 #
 # Create an Icepak project and import the step.
 
-new_project = os.path.join(temp_dir.name, generate_unique_name("example") + ".aedt")
+new_project = os.path.join(temp_dir.name, "example.aedt")
 app = pyaedt.Icepak(project=new_project)
 app.modeler.import_3d_cad(file_path)
 
@@ -131,7 +132,13 @@
 # Close the project and release AEDT.
 
 app.release_desktop()
+time.sleep(3)   # Allow Electronics Desktop to shut down before cleaning the temporary project folder.
 
-# ## Clean temporary directory
+# ## Cleanup
+#
+# All project files are saved in the folder ``temp_dir.name``.
+# If you've run this example as a Jupyter notebook you
+# can retrieve those project files. The following cell removes
+# all temporary files, including the project folder.
 
 temp_dir.cleanup()

examples/01-Modeling-Setup/HFSS_CoordinateSystem.py

@@ -2,42 +2,32 @@
 #
 # This example shows how you can use PyAEDT to create and modify coordinate systems in the modeler.
 #
-# ## Perform required imports
-#
-# Perform required imports
+# ## Preparation
+# Import the required packages
 
 import tempfile
-
+import time
 import pyaedt
+import os
 
-# Set constant values
+# Define constants
 
 AEDT_VERSION = "2024.1"
-
-# ## Set non-graphical mode
-
-# Set non-graphical mode.
-# You can set ``non_graphical`` either to ``True`` or ``False``.
-
-non_graphical = False
+NG_MODE = False  # Open Electronics UI when the application is launched.
 
 # ## Create temporary directory
 
-temp_dir = tempfile.TemporaryDirectory(suffix="_ansys")
+temp_dir = tempfile.TemporaryDirectory(suffix=".ansys")
 
 # ## Launch AEDT
 
-d = pyaedt.launch_desktop(
-    version=AEDT_VERSION, non_graphical=non_graphical, new_desktop=True
-)
+d = pyaedt.launch_desktop(version=AEDT_VERSION, non_graphical=NG_MODE, new_desktop=True)
 
 # ## Insert HFSS design
 #
 # Insert an HFSS design with the default name.
 
-project_name = pyaedt.generate_unique_project_name(
-    rootname=temp_dir.name, project_name="CoordSysDemo"
-)
+project_name = os.path.join(temp_dir.name, "CoordSysDemo.aedt")
 hfss = pyaedt.Hfss(project=project_name)
 
 # ## Create coordinate system
@@ -57,7 +47,8 @@
 cs1.props["OriginY"] = 10
 cs1.props["OriginZ"] = 10
 
-# Pointing vectors can be changed
+# The orientation of the coordinate system can be modified by
+# updating the direction vectors for the coordinate system.
 
 ypoint = [0, -1, 0]
 cs1.props["YAxisXvec"] = ypoint[0]
@@ -72,13 +63,17 @@
 
 # ## Change coordinate system mode
 #
-# Use the ``change_cs_mode`` method to change the mode. Options are ``0``
-# for axis/position, ``1`` for Euler angle ZXZ, and ``2`` for Euler angle ZYZ.
+# Use the ``change_cs_mode`` method to change the mode. Options are
+#
+# - ``0`` for axis/position
+# - ``1`` for Euler angle ZXZ
+# - ``2`` for Euler angle ZYZ.
+#
 # Here ``1`` sets Euler angle ZXZ as the mode.
 
 cs1.change_cs_mode(1)
 
-# In the new mode, these properties can be edited
+# The following lines use the ZXZ Euler angle definition to rotate the coordinate system.
 
 cs1.props["Phi"] = "10deg"
 cs1.props["Theta"] = "22deg"
@@ -90,28 +85,33 @@
 
 cs1.delete()
 
-# ## Create coordinate system by defining axes
+# ## Define a new coordinate system
 #
-# Create a coordinate system by defining the axes. During creation, you can
-# specify all coordinate system properties.
+# Create a coordinate system by defining the axes. You can
+# specify all coordinate system properties as shown here.
 
 cs2 = hfss.modeler.create_coordinate_system(
-    name="CS2", origin=[1, 2, 3.5], mode="axis", x_pointing=[1, 0, 1], y_pointing=[0, -1, 0]
+    name="CS2",
+    origin=[1, 2, 3.5],
+    mode="axis",
+    x_pointing=[1, 0, 1],
+    y_pointing=[0, -1, 0],
 )
 
-# ## Create coordinate system by defining Euler angles
-#
-# Create a coordinate system by defining Euler angles.
+# A new coordinate system can also be created based on the Euler angle convention.
 
 cs3 = hfss.modeler.create_coordinate_system(
     name="CS3", origin=[2, 2, 2], mode="zyz", phi=10, theta=20, psi=30
 )
 
-# ## Create coordinate system by defining view
+# Create a coordinate system that is defined by standard views in the modeler. The options are 
+#
+# - ``"iso"``
+# - ``"XY"``
+# - ``"XZ"``
+# - ``"XY"``.
 #
-# Create a coordinate system by defining the view. Options are ``"iso"``,
-# ``"XY"``, ``"XZ"``, and ``"XY"``. Here ``"iso"`` is specified.
-# The axes are set automatically.
+# Here ``"iso"`` is specified. The axes are set automatically.
 
 cs4 = hfss.modeler.create_coordinate_system(
     name="CS4", origin=[1, 0, 0], reference_cs="CS3", mode="view", view="iso"
@@ -123,10 +123,10 @@
 # specify the axis and angle rotation, this data is automatically translated
 # to Euler angles.
 
-cs5 = hfss.modeler.create_coordinate_system(name="CS5", mode="axisrotation", u=[1, 0, 0], theta=123)
+cs5 = hfss.modeler.create_coordinate_system(
+    name="CS5", mode="axisrotation", u=[1, 0, 0], theta=123
+)
 
-# ## Create face coordinate system
-#
 # Face coordinate systems are bound to an object face.
 # First create a box and then define the face coordinate system on one of its
 # faces. To create the reference face for the face coordinate system, you must
@@ -138,29 +138,27 @@
     face=face, origin=face.edges[0], axis_position=face.edges[1], name="FCS1"
 )
 
-# ## Create face coordinate system centered on face
-#
 # Create a face coordinate system centered on the face with the X axis pointing
 # to the edge vertex.
 
 fcs2 = hfss.modeler.create_face_coordinate_system(
     face=face, origin=face, axis_position=face.edges[0].vertices[0], name="FCS2"
 )
 
-# ## Swap X and Y axes of face coordinate system
-#
 # Swap the X axis and Y axis of the face coordinate system. The X axis is the
 # pointing ``axis_position`` by default. You can optionally select the Y axis.
 
 fcs3 = hfss.modeler.create_face_coordinate_system(
     face=face, origin=face, axis_position=face.edges[0], axis="Y"
 )
 
-# Axis can also be changed after coordinate system creation
+# The face coordinate system can also be rotated by changing the
+# reference axis.
+
 fcs3.props["WhichAxis"] = "X"
 
 
-# ## Apply a rotation around Z axis
+# ### Rotate the coordinate system
 #
 # Apply a rotation around the Z axis. The Z axis of a face coordinate system
 # is always orthogonal to the face. A rotation can be applied at definition.
@@ -170,11 +168,11 @@
     face=face, origin=face, axis_position=face.edges[1], rotation=10.3
 )
 
-# ### Rotation can also be changed after coordinate system creation
+# Rotation can also be changed after coordinate system creation
 
 fcs4.props["ZRotationAngle"] = "3deg"
 
-# ## Apply offset to X and Y axes of face coordinate system
+# ### Offset the coordinate system
 #
 # Apply an offset to the X axis and Y axis of a face coordinate system.
 # The offset is in respect to the face coordinate system itself.
@@ -183,15 +181,15 @@
     face=face, origin=face, axis_position=face.edges[2], offset=[0.5, 0.3]
 )
 
-# ### The offset can also be changed after the coordinate system is created.
+# The offset can be changed after the coordinate system has been created.
 
 fcs5.props["XOffset"] = "0.2mm"
 fcs5.props["YOffset"] = "0.1mm"
 
-# ## Create coordinate system relative to face coordinate system
+# ### Dependent coordinate systems
 #
-# Create a coordinate system relative to a face coordinate system. Coordinate
-# systems and face coordinate systems interact with each other.
+# The use of dependent coordinate systems can simplify model creation. The following
+# cell demonstrates how to create a coordinate system whose reference is the face coordinate system.
 
 face = box.faces[1]
 fcs6 = hfss.modeler.create_face_coordinate_system(
@@ -201,45 +199,59 @@
     name="CS_FCS", origin=[0, 0, 0], reference_cs=fcs6.name, mode="view", view="iso"
 )
 
-# ## Create object coordinate system
+# ### Object coordinate systems
 #
-# Create object coordinate system with origin on face
+# A coordinate system can also be defined relative to elements
+# belonging to an object. For example, the coordinate system can be
+# connected to an object face.
 
 obj_cs = hfss.modeler.create_object_coordinate_system(
-    obj=box, origin=box.faces[0], x_axis=box.edges[0], y_axis=[0, 0, 0], name="box_obj_cs"
+    assignment=box,
+    origin=box.faces[0],
+    x_axis=box.edges[0],
+    y_axis=[0, 0, 0],
+    name="box_obj_cs",
 )
 obj_cs.rename("new_obj_cs")
 
-# ## Create object coordinate system
-#
-# Create object coordinate system with origin on edge
+# Create an object coordinate system whose origin is linked to the edge of an object.
 
 obj_cs_1 = hfss.modeler.create_object_coordinate_system(
-    obj=box.name, origin=box.edges[0], x_axis=[1, 0, 0], y_axis=[0, 1, 0], name="obj_cs_1"
+    assignment=box.name,
+    origin=box.edges[0],
+    x_axis=[1, 0, 0],
+    y_axis=[0, 1, 0],
+    name="obj_cs_1",
 )
 obj_cs_1.set_as_working_cs()
 
-# ## Create object coordinate system
-#
-# Create object coordinate system with origin specified on point
+# Create object coordinate system with origin specified on a point within an object.
 
 obj_cs_2 = hfss.modeler.create_object_coordinate_system(
-    obj=box.name, origin=[0, 0.8, 0], x_axis=[1, 0, 0], y_axis=[0, 1, 0], name="obj_cs_2"
+    assignment=box.name,
+    origin=[0, 0.8, 0],
+    x_axis=[1, 0, 0],
+    y_axis=[0, 1, 0],
+    name="obj_cs_2",
 )
 new_obj_cs_2 = hfss.modeler.duplicate_coordinate_system_to_global(obj_cs_2)
 obj_cs_2.delete()
 
-# ## Create object coordinate system
-#
-# Create object coordinate system with origin on vertex
+# Create object coordinate system with origin on vertex.
 
 obj_cs_3 = hfss.modeler.create_object_coordinate_system(
-    obj=box.name, origin=box.vertices[1], x_axis=box.faces[2], y_axis=box.faces[4], name="obj_cs_3"
+    obj=box.name,
+    origin=box.vertices[1],
+    x_axis=box.faces[2],
+    y_axis=box.faces[4],
+    name="obj_cs_3",
 )
 obj_cs_3.props["MoveToEnd"] = False
 obj_cs_3.update()
 
-# ## Get all coordinate systems
+# ### Get all coordinate systems
+#
+# All coordinate systems can easily be retrieved and subsequently manipulated.
 
 css = hfss.modeler.coordinate_systems
 names = [i.name for i in css]
@@ -268,7 +280,11 @@
 # Close the project and release AEDT.
 
 d.release_desktop()
+time.sleep(3)
 
-# ## Clean temporary directory
+# ## Cleanup
+#
+# All project files are saved in the folder ``temp_dir.name``. If you've run this example as a Jupyter notebook you
+# can retrieve those project files. The following cell removes all temporary files, including the project folder.
 
 temp_dir.cleanup()