DOCS: Update GDS Example to match template (#392)

Co-authored-by: svandenb-dev <[email protected]>

Author: Devin-Crawford

examples/00_edb/legacy_standalone/GDS_workflow.py

@@ -1,78 +1,110 @@
-# # EDB: Importing GDS file
+# # GDS Import
 #
-# This example demonstrates how to import GDS files and translate their information to an EDB file.
+# Integrated circuit layout data is defined in GDS data which specifies the layout
+# geometry. Additionally, layer mapping and layer material information is defined in a
+# technology file.
+#
+# This example demonstrates how to import GDS files and translate GDS data
+# into an EDB file along with some simplified technology data
+# for subsequent use in HFSS 3D Layout.
+#
+# Keywords: **GDS**, **RFIC**
 
-# Perform imports.
+# ## Prerequisites
+#
+# ### Perform imports
 
-# +
 import os
 import tempfile
 from pyedb.dotnet.edb import Edb
 from pyedb.misc.downloads import download_file
 from ansys.aedt.core.hfss3dlayout import  Hfss3dLayout
-# -
 
-# ## Case 1: Import a GDS file.
+# ### Define constants
+# Constants help ensure consistency and avoid repetition throughout the example.
+
+AEDT_VERSION = "2025.1"
+NG_MODE = False  # Open AEDT UI when it is launched.
+
+# ### Create temporary directory
+#
+# Create a temporary working directory.
+# The name of the working folder is stored in ``temp_folder.name``.
+#
+# > **Note:** The final cell in the notebook cleans up the temporary folder. If you want to
+# > retrieve the AEDT project and data, do so before executing the final cell in the notebook.
+
+temp_folder = tempfile.TemporaryDirectory(suffix=".ansys")
+
+# ### Import a GDS file.
+#
+# Download the test case folder and copy it to the working directory. The 
+# method ``download_file()`` retrieves example data from the 
+# [Ansys GitHub "example_data" repository](https://github.com/ansys/example-data/tree/main/pyaedt).
 #
-# Download the test case folder and copy it to a temporary folder.
 # The following files are used in this example:
 #
-# - XML_Automation.xml
-#   defines physical information such
-#   as material properties, stackup layers, and boundary conditions.
-# - Model.map
-#   maps properties to stackup layers.
+# - ``Model.xml`` defines physical information such
+#   as material properties, stackup layer names, and boundary conditions.
+# - ``Model.gds`` contains the GDS data for the layout.
+# - ``Model.map`` maps properties to stackup layers.
 
 # +
-temp_dir = tempfile.TemporaryDirectory(suffix=".ansys")
 control_fn = "Model.xml"
 gds_fn = "Model.gds"
 layer_map = "Model.map"
 
-local_path = download_file("gds", destination=temp_dir.name)
-my_control_file = os.path.join(local_path, control_fn)
-my_map_file = os.path.join(local_path, layer_map)
+local_path = download_file("gds", destination=temp_folder.name)
+control_file = os.path.join(local_path, control_fn)
+map_file = os.path.join(local_path, layer_map)
 gds_in = os.path.join(local_path, gds_fn)
 # -
 
-# ## Open EDB
+# ### Open the EDB
 #
-# Import the gds and open the edb. Each gds is followed either by a control file (XML) or a technology file (IRCX, VLC.TECH, or ITF).
-# Then a MAP file is also regularly used to map the stackup layers, and finally in some cases a layer filter (XML) is deployed, when
+# Each GDS file requires a control file (XML) or a technology file (IRCX, VLC.TECH, or ITF)
+# that maps the GDS geometry to a physical layer in the stackup.
+# The MAP file is also regularly used to map the stackup layers, and finally in some cases a layer filter (XML) is deployed, when
 # only a part of the stackup is needed.
+#
+# Open the EDB by creating an instance of the ``Edb`` class.
 
-# +
-# Select EDB version (change it manually if needed, e.g. "2025.1")
-version = "2025.1"
-print(f"EDB version: {version}")
-
-edb = Edb(gds_in, edbversion=version, control_file=my_control_file, map_file=my_map_file)
-
-# ## Plot stackup
+edb = Edb(gds_in, edbversion=AEDT_VERSION, control_file=control_file, map_file=map_file)
 
+# ### View the layer stackup
 
 edb.stackup.plot()
 
-# ## Save and close EDB
+# ### Save and close the EDB
 #
-# Save the project.
-
-edb1_path = os.path.join(temp_dir.name, "gds_design.aedb")
+# The GDS file has been converted to an EDB and is ready for subsequent processing either in the
+# 3D Layout UI of Electronics Desktop or using 
+# PyEDB. 
+# The following commands save and close the EDB. 
 
-edb.save_as(edb1_path)
+edb_path = os.path.join(temp_folder.name, "gds_design.aedb")
+edb.save_as(edb_path)
+edb.close()
 
-# Close the project.
-
-edb.close_edb()
-
-# ## Open both EDB files with HFSS 3D Layout, and observe the design / confirm the robustness from GDS to EDB.
+# ## View the layout
+# ### Open the EDB in Electronics Desktop
+#
+# The following command opens the EDB in Electronics Desktop. If you're running this example locally, you should see something like this:
+#
+# <img src="_static/layout.png" width="800">
 
-h3d_gds = Hfss3dLayout(project=edb1_path, version=version, new_desktop=True)
+h3d = Hfss3dLayout(project=edb_path, version=AEDT_VERSION, new_desktop=NG_MODE)
 
-# ## Close the HFSS 3D Layout design and release the dekstop.
+# ### Close the HFSS 3D Layout 
+# The following command releases Ansys Electronics Desktop and closes the project.
 
-h3d_gds.release_desktop()
+h3d.release_desktop()
 
-# Clean up the temporary folder.
+# ### Clean up
+#
+# All project files are saved in the folder ``temp_folder.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()
+temp_folder.cleanup()