Added new method get_traces_for_plot to get trace list ready to be pl…

…otted. (#843)

* Added new method get_traces_for_plot to get trace list ready to be plotted.
Refactored get_excitations_name. In some Classes it was a property in some other a method.
Deprecated and replaced with excitations property

* Added new method get_traces_for_plot to get trace list ready to be plotted.
Refactored get_excitations_name. In some Classes it was a property in some other a method.
Deprecated and replaced with excitations property

* fixed flake8

* added additional UT

* fixed method in q3d

* fixed method in q3d

* add coverage comments

* black fix

_unittest/test_12_PostProcessing.py

@@ -30,14 +30,11 @@ class TestClass:
     def setup_class(self):
         # set a scratch directory and the environment / test data
         with Scratch(scratch_path) as self.local_scratch:
-            try:
-                example_project = os.path.join(local_path, "example_models", test_project_name + ".aedtz")
-                self.test_project = self.local_scratch.copyfile(example_project)
-                example_project2 = os.path.join(local_path, "example_models", test_field_name + ".aedtz")
-                self.test_project2 = self.local_scratch.copyfile(example_project2)
-                self.aedtapp = Hfss(self.test_project)
-            except:
-                pass
+            example_project = os.path.join(local_path, "example_models", test_project_name + ".aedtz")
+            self.test_project = self.local_scratch.copyfile(example_project)
+            example_project2 = os.path.join(local_path, "example_models", test_field_name + ".aedtz")
+            self.test_project2 = self.local_scratch.copyfile(example_project2)
+            self.aedtapp = Hfss(self.test_project)
 
     def teardown_class(self):
         self.aedtapp._desktop.ClearMessages("", "", 3)

_unittest/test_20_HFSS.py

@@ -466,11 +466,9 @@ def test_18_create_sources_on_objects(self):
         port = self.aedtapp.create_voltage_source_from_objects(
             box1.name, "BoxVolt2", self.aedtapp.AxisDir.XNeg, "Volt1"
         )
-        assert port.name in self.aedtapp.modeler.get_excitations_name()
-        port = self.aedtapp.create_current_source_from_objects(
-            "BoxVolt1", "BoxVolt2", self.aedtapp.AxisDir.XPos, "Curr1"
-        )
-        assert port.name in self.aedtapp.modeler.get_excitations_name()
+        assert port.name in self.aedtapp.excitations
+        port = self.aedtapp.create_current_source_from_objects("BoxVolt1", "BoxVolt2", self.aedtapp.AxisDir.XPos)
+        assert port.name in self.aedtapp.excitations
 
     def test_19_create_lumped_on_sheet(self):
         rect = self.aedtapp.modeler.create_rectangle(
@@ -479,14 +477,14 @@ def test_19_create_lumped_on_sheet(self):
         port = self.aedtapp.create_lumped_port_to_sheet(
             rect.name, self.aedtapp.AxisDir.XNeg, 50, "Lump_sheet", True, False
         )
-        assert port.name + ":1" in self.aedtapp.modeler.get_excitations_name()
+        assert port.name + ":1" in self.aedtapp.excitations
 
     def test_20_create_voltage_on_sheet(self):
         rect = self.aedtapp.modeler.create_rectangle(
             self.aedtapp.PLANE.XY, [0, 0, 0], [10, 2], name="lump_volt", matname="Copper"
         )
         port = self.aedtapp.assign_voltage_source_to_sheet(rect.name, self.aedtapp.AxisDir.XNeg, "LumpVolt1")
-        assert port.name in self.aedtapp.modeler.get_excitations_name()
+        assert port.name in self.aedtapp.excitations
         assert self.aedtapp.get_property_value("BoundarySetup:LumpVolt1", "VoltageMag", "Excitation") == "1V"
 
     def test_21_create_open_region(self):
@@ -709,11 +707,11 @@ def test_45_terminal_port(self):
         port = self.aedtapp.create_lumped_port_between_objects(
             box1, box2.name, self.aedtapp.AxisDir.XNeg, 50, "Lump1", True, False
         )
-        assert "Lump1_T1" in self.aedtapp.get_excitations_name()
+        assert "Lump1_T1" in self.aedtapp.excitations
         port2 = self.aedtapp.create_lumped_port_to_sheet(
             sheet.name, self.aedtapp.AxisDir.XNeg, 50, "Lump_sheet", True, False, reference_object_list=[box1]
         )
-        assert port2.name + "_T1" in self.aedtapp.modeler.get_excitations_name()
+        assert port2.name + "_T1" in self.aedtapp.excitations
 
         box1 = self.aedtapp.modeler.create_box([-40, -40, -20], [80, 80, 10], name="gnd", matname="copper")
         box2 = self.aedtapp.modeler.create_box([-40, -40, 10], [80, 80, 10], name="sig", matname="copper")
@@ -728,3 +726,7 @@ def test_46_mesh_settings(self):
     def test_47_convert_near_field(self):
         example_project = os.path.join(local_path, "example_models", "nf_test")
         assert os.path.exists(convert_nearfield_data(example_project, self.local_scratch.path))
+
+    def test_48_traces(self):
+        assert len(self.aedtapp.excitations) > 0
+        assert len(self.aedtapp.get_traces_for_plot()) > 0

_unittest/test_21_Circuit.py

@@ -147,6 +147,7 @@ def test_12_connect_components(self):
         myres = self.aedtapp.modeler.schematic.create_resistor("R100", 50)
         mycap = self.aedtapp.modeler.schematic.create_capacitor("C100", 1e-12)
         portname = self.aedtapp.modeler.schematic.create_interface_port("Port1")
+        assert len(self.aedtapp.excitations) > 0
         assert "Port1" in portname.name
         assert myind.pins[0].connect_to_component(portname.pins[0])
         assert myind.pins[1].connect_to_component(myres.pins[1])

_unittest/test_31_Q3D.py

@@ -72,6 +72,7 @@ def test_07_create_source_sinks(self):
         sink = self.aedtapp.assign_sink_to_objectface("MyCylinder", axisdir=3, sink_name="Sink1")
         assert source.name == "Source1"
         assert sink.name == "Sink1"
+        assert len(self.aedtapp.excitations) > 0
 
     def test_07B_create_source_tosheet(self):
         self.aedtapp.modeler.create_circle(self.aedtapp.PLANE.XY, [0, 0, 0], 4, name="Source1")

_unittest/test_41_3dlayout_modeler.py

@@ -184,6 +184,7 @@ def test_12_create_line(self):
     def test_13a_create_edge_port(self):
         assert self.aedtapp.create_edge_port("line1", 3, False)
         assert self.aedtapp.create_edge_port("line1", 0, True)
+        assert len(self.aedtapp.excitations) > 0
 
     def test_14a_create_coaxial_port(self):
         assert self.aedtapp.create_coax_port("Via123", "Bottom", "Top", 10, 10, 10, 10)

examples/02-HFSS/HFSS3DLayout_Via.py

@@ -91,9 +91,8 @@
 # This example solves and plots results.
 
 h3d.analyze_nominal()
-h3d.post.create_rectangular_plot(
-    ["db(S(Port1,Port1))", "db(S(Port1,Port2))"], families_dict=h3d.available_variations.nominal_w_values_dict
-)
+traces = h3d.get_traces_for_plot(first_element_filter="Port1")
+h3d.post.create_rectangular_plot(traces, families_dict=h3d.available_variations.nominal_w_values_dict)
 
 ###############################################################################
 # Close AEDT

examples/05-Q3D/Q3D_Example.py

@@ -116,7 +116,7 @@
 
 q.post.create_rectangular_plot(expression=data_plot_self, context="Original")
 
-data_plot_mutual = q.matrices[0].get_sources_for_plot(get_self_terms=False, get_mutual_terms=True)
+data_plot_mutual = q.get_traces_for_plot(get_self_terms=False, get_mutual_terms=True)
 
 q.post.create_rectangular_plot(expression=data_plot_mutual, context="Original", plot_type="Data Table")
 

examples/06-Multiphysics/Hfss_Mechanical.py

@@ -33,7 +33,7 @@
 # Starts HFSS
 # ~~~~~~~~~~~
 # Starts Hfss and initialize the Pyaedt object.
-non_graphical = True
+
 version = "2021.2"
 hfss = Hfss(project_temp_name, specified_version=version, non_graphical=non_graphical)
 pin_names = hfss.modeler.get_excitations_name()

pyaedt/application/Analysis.py

@@ -12,7 +12,7 @@
 import warnings
 from collections import OrderedDict
 
-from pyaedt.generic.general_methods import aedt_exception_handler, generate_unique_name
+from pyaedt.generic.general_methods import aedt_exception_handler, generate_unique_name, filter_tuple
 from pyaedt.generic.constants import (
     AXIS,
     PLANE,
@@ -483,8 +483,8 @@ def SolutionTypes(self):
         """
         return SOLUTIONS()
 
-    @aedt_exception_handler
-    def get_excitations_name(self):
+    @property
+    def excitations(self):
         """Get all excitation names.
 
         Returns
@@ -505,6 +505,82 @@ def get_excitations_name(self):
         except:
             return []
 
+    @aedt_exception_handler
+    def get_excitations_name(self):
+        """Get all excitation names.
+
+        .. deprecated:: 0.4.27
+           Use :func:`excitations` property instead.
+
+        Returns
+        -------
+        list
+            List of excitation names. Excitations with multiple modes will return one
+            excitation for each mode.
+
+        References
+        ----------
+
+        >>> oModule.GetExcitations
+        """
+        warnings.warn("`get_excitations_name` is deprecated. Use `excitations` property instead.", DeprecationWarning)
+        return self.excitations
+
+    @aedt_exception_handler
+    def get_traces_for_plot(
+        self,
+        get_self_terms=True,
+        get_mutual_terms=True,
+        first_element_filter=None,
+        second_element_filter=None,
+        category="dB(S",
+    ):
+        """Return a list of traces of specified design ready to be used in plot reports.
+
+        Parameters
+        ----------
+        get_self_terms : bool
+            Either if self terms have to be returned or not.
+        get_mutual_terms : bool
+            Either if mutual terms have to be returned or not.
+        first_element_filter : str, optional
+            Filter to apply to first element of equation. It accepts `*` and `?` as special characters.
+        second_element_filter : str, optional
+            Filter to apply to second element of equation. It accepts `*` and `?` as special characters.
+        category : str
+            Plot category name as in the report (including operator). Eg. "dB(S" is category Capacitance.
+
+        Returns
+        -------
+        list
+
+        Examples
+        --------
+        >>> from pyaedt import Q3d
+        >>> hfss = hfss(project_path)
+        >>> hfss.get_traces_for_plot(first_element_filter="Bo?1",
+        ...                           second_element_filter="GND*", category="dB(S")
+        """
+        if not first_element_filter:
+            first_element_filter = "*"
+        if not second_element_filter:
+            second_element_filter = "*"
+        list_output = []
+        end_str = ")" * (category.count("(") + 1)
+        if get_self_terms:
+            for el in self.excitations:
+                value = "{}({},{}{}".format(category, el, el, end_str)
+                if filter_tuple(value, first_element_filter, second_element_filter):
+                    list_output.append(value)
+        if get_mutual_terms:
+            for el1 in self.excitations:
+                for el2 in self.excitations:
+                    if el1 != el2:
+                        value = "{}({},{}{}".format(category, el1, el2, end_str)
+                        if filter_tuple(value, first_element_filter, second_element_filter):
+                            list_output.append(value)
+        return list_output
+
     @aedt_exception_handler
     def analyze_all(self):
         """Analyze all setup in an actual design.
@@ -1125,7 +1201,7 @@ def create_setup(self, setupname="MySetupAuto", setuptype=None, props={}):
             setuptype = self.design_solutions.default_setup
         name = self.generate_unique_setup_name(setupname)
         setup = Setup(self, setuptype, name)
-        if self.design_type == "HFSS" and not self.get_excitations_name() and "MaxDeltaS" in setup.props:
+        if self.design_type == "HFSS" and not self.excitations and "MaxDeltaS" in setup.props:
             new_dict = OrderedDict()
             for k, v in setup.props.items():
                 if k == "MaxDeltaS":

pyaedt/application/Analysis3DLayout.py

@@ -1,4 +1,5 @@
 import os
+import warnings
 
 from pyaedt.generic.general_methods import aedt_exception_handler, is_ironpython
 from pyaedt.modeler.Model3DLayout import Modeler3DLayout
@@ -136,10 +137,30 @@ def mesh(self):
         """
         return self._mesh
 
+    @property
+    def excitations(self):
+        """Get all excitation names.
+
+        Returns
+        -------
+        list
+            List of excitation names. Excitations with multiple modes will return one
+            excitation for each mode.
+
+        References
+        ----------
+
+        >>> oModule.GetExcitations
+        """
+        return list(self.oboundary.GetAllPortsList())
+
     @property
     def get_excitations_name(self):
         """Excitation names.
 
+        .. deprecated:: 0.4.27
+           Use :func:`excitations` property instead.
+
         Returns
         -------
         list
@@ -150,7 +171,8 @@ def get_excitations_name(self):
 
         >>> oModule.GetAllPortsList
         """
-        return list(self.oboundary.GetAllPortsList())
+        warnings.warn("`get_excitations_name` is deprecated. Use `excitations` property instead.", DeprecationWarning)
+        return self.excitations
 
     @property
     def get_all_sparameter_list(self, excitation_names=[]):
@@ -171,7 +193,7 @@ def get_all_sparameter_list(self, excitation_names=[]):
 
         """
         if not excitation_names:
-            excitation_names = self.get_excitations_name
+            excitation_names = self.excitations
         spar = []
         k = 0
         for i in excitation_names:
@@ -234,7 +256,7 @@ def get_all_return_loss_list(self, excitation_names=[], excitation_name_prefix="
         >>> oModule.GetAllPorts
         """
         if not excitation_names:
-            excitation_names = self.get_excitations_name
+            excitation_names = self.excitations
         if excitation_name_prefix:
             excitation_names = [i for i in excitation_names if excitation_name_prefix.lower() in i.lower()]
         spar = []
@@ -271,9 +293,9 @@ def get_all_insertion_loss_list(self, trlist=[], reclist=[], tx_prefix="", rx_pr
         """
         spar = []
         if not trlist:
-            trlist = [i for i in self.get_excitations_name if tx_prefix in i]
+            trlist = [i for i in self.excitations if tx_prefix in i]
         if not reclist:
-            reclist = [i for i in self.get_excitations_name if rx_prefix in i]
+            reclist = [i for i in self.excitations if rx_prefix in i]
         if len(trlist) != len(reclist):
             self.logger.error("The TX and RX lists should be same length.")
             return False
@@ -305,7 +327,7 @@ def get_next_xtalk_list(self, trlist=[], tx_prefix=""):
         """
         next = []
         if not trlist:
-            trlist = [i for i in self.get_excitations_name if tx_prefix in i]
+            trlist = [i for i in self.excitations if tx_prefix in i]
         for i in trlist:
             k = trlist.index(i) + 1
             while k < len(trlist):
@@ -346,9 +368,9 @@ def get_fext_xtalk_list(self, trlist=[], reclist=[], tx_prefix="", rx_prefix="",
         """
         fext = []
         if not trlist:
-            trlist = [i for i in self.get_excitations_name if tx_prefix in i]
+            trlist = [i for i in self.excitations if tx_prefix in i]
         if not reclist:
-            reclist = [i for i in self.get_excitations_name if rx_prefix in i]
+            reclist = [i for i in self.excitations if rx_prefix in i]
         for i in trlist:
             for k in reclist:
                 if not skip_same_index_couples or reclist.index(k) != trlist.index(i):