Skip to content

Improved documentation #3716

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Oct 9, 2023
Merged

Improved documentation #3716

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
03fa639
Improved documentation
Oct 6, 2023
c0172e0
Update pyaedt/modeler/cad/Primitives3D.py
maxcapodi78 Oct 9, 2023
037ec49
Update pyaedt/modeler/cad/Primitives3D.py
maxcapodi78 Oct 9, 2023
22e0291
Update pyaedt/modeler/cad/Primitives3D.py
maxcapodi78 Oct 9, 2023
9da069e
Update pyaedt/modeler/cad/Primitives3D.py
maxcapodi78 Oct 9, 2023
a403b32
Update pyaedt/modeler/cad/Primitives3D.py
maxcapodi78 Oct 9, 2023
0730dab
Update pyaedt/modeler/cad/Primitives3D.py
maxcapodi78 Oct 9, 2023
e29cae8
Update pyaedt/modeler/cad/Primitives3D.py
maxcapodi78 Oct 9, 2023
3bdb34d
Update pyaedt/modeler/cad/Primitives3D.py
maxcapodi78 Oct 9, 2023
e067f7b
Update pyaedt/modeler/cad/Primitives3D.py
maxcapodi78 Oct 9, 2023
a1fcf8a
Update pyaedt/modeler/cad/Primitives3D.py
maxcapodi78 Oct 9, 2023
800490a
Update pyaedt/modeler/cad/Primitives3D.py
maxcapodi78 Oct 9, 2023
f3260a0
Update pyaedt/modeler/cad/Primitives3D.py
maxcapodi78 Oct 9, 2023
fe26a75
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Oct 9, 2023
fdfce6b
added docstring
Oct 9, 2023
3978d22
Merge remote-tracking branch 'origin/improve_docs_with_examples' into…
Oct 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions _unittest/test_01_downloads.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@ def test_13_download_specific_folder(self):
def test_14_download_icepak_3d_component(self):
assert self.examples.download_icepak_3d_component()

@pytest.mark.skipif(is_linux, reason="Failing download files")
def test_15_download_fss_file(self):
example_folder = self.examples.download_FSS_3dcomponent()
assert os.path.exists(example_folder)
150 changes: 143 additions & 7 deletions pyaedt/modeler/cad/Primitives3D.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,13 +82,21 @@ def create_box(self, position, dimensions_list, name=None, matname=None):

Examples
--------
The following examples shows how to create a box in HFSS.
The main parameters are position that provides the origin of the
box and dimensions_list that provide the box sizes.
Copy link
Member

@PipKat PipKat Oct 6, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The main parameters are position that provides the origin of the
box and dimensions_list that provide the box sizes.
The main parameters are ``position``, which provides the origin of the
box, and ``dimensions_list``, which provide the box sizes.

Should "main" be "required" instead? Is the intent to indicate which parameters are required versus optional? I've not seen any other library do this type of parameter breakdown in their examples. Is it based on user feedback? Usually, the names of the parameters are clear enough--and aren't descriptions of all these parameters easily found in the "Parameters" section of the method? Also, if all methods apply to all 3D applications, perhaps this statement and the listing of these 3D apps can appear only once, as a note for the class maybe? I've edited the content for the other "Examples" sections, but I think you consider these points. And, if you decide to do this type of breakdown, I'd recommend using lists for the descriptions of the parameters, at least where there are several of them.

The parameter matname is optional and allows to set the material name of the box.
The parameter name is optional and allows to give a name to the box.
This method applies to all 3D applications: HFSS, Q3D, Icepak, Maxwell 3D, Mechanical.

>>> from pyaedt import hfss
>>> hfss = Hfss()
>>> origin = [0,0,0]
>>> dimensions = [10,5,20]
>>> #Material and name are not mandatory fields
>>> box_object = hfss.modeler.primivites.create_box(origin, dimensions, name="mybox", matname="copper")
>>> box_object = hfss.modeler.primivites.create_box(position=origin,
... dimensions_list=dimensions,
... name="mybox",
... matname="copper")

"""
if len(position) != 3:
Expand Down Expand Up @@ -145,9 +153,16 @@ def create_cylinder(self, cs_axis, position, radius, height, numSides=0, name=No

Examples
--------
The following examples shows how to create a cylinder in HFSS.
The main parameters are ``cs_axis`` that provides the direction axis of the cylinder,
``position`` that provides the origin of the cylinder, ``radius`` of the cylinder, ``height`` of the cylinder.
The parameter ``matname`` is optional and allows to set the material name of the cylinder.
The parameter ``"name"`` is optional and allows to give a name to the cylinder.
This method applies to all 3D applications: HFSS, Q3D, Icepak, Maxwell 3D, Mechanical.

>>> from pyaedt import Hfss
>>> aedtapp = Hfss()
>>> cylinder_object = aedtapp.modeler..create_cylinder(cs_axis='Z', position=[0,0,0],
>>> cylinder_object = aedtapp.modeler.create_cylinder(cs_axis='Z', position=[0,0,0],
... radius=2, height=3, name="mycyl",
... matname="vacuum")

Expand Down Expand Up @@ -220,6 +235,14 @@ def create_polyhedron(

Examples
--------
The following examples shows how to create a regular polyhedron in HFSS.
The main parameters are cs_axis that provides the direction axis of the polyhedron,
center_position that provides the center of the polyhedron, start_position of the polyhedron,
height of the polyhedron and num_sides to determine the number of sides.
The parameter matname is optional and allows to set the material name of the polyhedron.
The parameter name is optional and allows to give a name to the polyhedron.
This method applies to all 3D applications: HFSS, Q3D, Icepak, Maxwell 3D, Mechanical.
Copy link
Member

@PipKat PipKat Oct 6, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The following examples shows how to create a regular polyhedron in HFSS.
The main parameters are cs_axis that provides the direction axis of the polyhedron,
center_position that provides the center of the polyhedron, start_position of the polyhedron,
height of the polyhedron and num_sides to determine the number of sides.
The parameter matname is optional and allows to set the material name of the polyhedron.
The parameter name is optional and allows to give a name to the polyhedron.
This method applies to all 3D applications: HFSS, Q3D, Icepak, Maxwell 3D, Mechanical.
This example shows how to create a regular polyhedron in HFSS.
The main parameters are ``cs_axis``, `` center_position``, ``start_position``,
``height``, and ``num_sides``. The ``cs_axis`` parameter provides the direction
axis of the polyhedron. The ``center_position`` parameter provides the center
of the polyhedron. The three other parameters provide the start position,
height, and number of sides of the polyhedron.
The optional parameter ``matname`` allows you to set the material name of
the polyhedron. The optional parameter ``name`` allows you to assign a name
to the polyhedron.
This method applies to all 3D applications: HFSS, Q3D, Icepak, Maxwell 3D, and
Mechanical.


>>> from pyaedt import Hfss
>>> aedtapp = Hfss()
>>> ret_obj = aedtapp.modeler.create_polyhedron(cs_axis='X', center_position=[0, 0, 0],
Expand Down Expand Up @@ -257,7 +280,7 @@ def create_cone(self, cs_axis, position, bottom_radius, top_radius, height, name
cs_axis : str
Axis of rotation of the starting point around the center point.
The default is ``None``, in which case the Z axis is used.
center_position : list, optional
position : list, optional
List of ``[x, y, z]`` coordinates for the center position
of the bottom of the cone.
bottom_radius : float
Expand Down Expand Up @@ -285,6 +308,15 @@ def create_cone(self, cs_axis, position, bottom_radius, top_radius, height, name

Examples
--------
The following examples shows how to create a cone in HFSS.
The main parameters are ``cs_axis`` that provides the direction axis of the cone,
``position`` that provides the starting point of the cone, ``bottom_radius`` and ``top_radius`` are the
radius of the cone and ``height`` of the cone.
The parameter ``matname`` is optional and allows to set the material name of the cone.
The parameter ``name`` is optional and allows to give a name to the cone.
This method applies to all 3D applications: HFSS, Q3D, Icepak, Maxwell 3D, Mechanical.


>>> from pyaedt import Hfss
>>> aedtapp = Hfss()
>>> cone_object = aedtapp.modeler.create_cone(cs_axis='Z', position=[0, 0, 0],
Expand Down Expand Up @@ -349,6 +381,14 @@ def create_sphere(self, position, radius, name=None, matname=None):

Examples
--------
The following examples shows how to create a sphere in HFSS.
The main parameters are ``position`` which provides the center of the sphere and
``radius`` which is the sphere radius.
The parameter ``matname`` is optional and allows to set the material name of the sphere.
The parameter ``name`` is optional and allows to give a name to the sphere.
This method applies to all 3D applications: HFSS, Q3D, Icepak, Maxwell 3D, Mechanical.


>>> from pyaedt import Hfss
>>> aedtapp = Hfss()
>>> ret_object = aedtapp.modeler.create_sphere(position=[0,0,0], radius=2,
Expand Down Expand Up @@ -409,11 +449,15 @@ def create_torus(self, center, major_radius, minor_radius, axis=None, name=None,
Examples
--------
Create a torus named ``"mytorus"`` about the Z axis with a major
radius of 1, minor radius of 0.5, and a material of ``"copper"``.
radius of 1 , minor radius of 0.5, and a material of ``"copper"``.
The parameter ``matname`` is optional and allows to set the material name of the sphere.
The parameter ``name`` is optional and allows to give a name to the sphere.
This method applies to all 3D applications: HFSS, Q3D, Icepak, Maxwell 3D, Mechanical.

>>> from pyaedt import Hfss
>>> hfss = Hfss()
>>> origin = [0, 0, 0]
>>> torus = hfss.modeler.create_torus(origin, major_radius=1,
>>> torus = hfss.modeler.create_torus(center=origin, major_radius=1,
... minor_radius=0.5, axis="Z",
... name="mytorus", material_name="copper")

Expand Down Expand Up @@ -686,6 +730,23 @@ def create_circle(

>>> oEditor.CreateCircle

Examples
--------
The following examples shows how to create a circle in HFSS.
The main parameters are ``cs_plane`` that provides the plane on which the circle is designed,
``position`` that provides the origin of the circle, ``radius`` of the circle,
``num_sides`` the number of discrete sides of the circle.
The parameter ``matname`` is optional and allows to set the material name of the circle.
The parameter ``name`` is optional and allows to give a name to the circle.
This method applies to all 3D applications: HFSS, Q3D, Icepak, Maxwell 3D, Mechanical.

>>> from pyaedt import Hfss
>>> aedtapp = Hfss()
>>> circle_object = aedtapp.modeler.create_circle(cs_plane='Z', position=[0,0,0],
... radius=2, num_sides=8, name="mycyl",
... matname="vacuum")


"""
non_model_flag = ""
if non_model:
Expand Down Expand Up @@ -741,6 +802,24 @@ def create_ellipse(self, cs_plane, position, major_radius, ratio, is_covered=Tru

>>> oEditor.CreateEllipse

Examples
--------
The following examples shows how to create an ellipse in HFSS.
The main parameters are ``cs_plane`` that provides the plane on which the ellipse is designed,
``position`` that provides the origin of the ellipse, ``major_radius`` of the ellipse,
``ratio`` between major radius and minor radius of the ellipse,
``is_covered`` a flag to determine if ellipse is covered or no.
The parameter ``matname`` is optional and allows to set the material name of the ellipse.
The parameter ``name`` is optional and allows to give a name to the ellipse.
This method applies to all 3D applications: HFSS, Q3D, Icepak, Maxwell 3D, Mechanical.

>>> from pyaedt import Hfss
>>> aedtapp = Hfss()
>>> ellipse = aedtapp.modeler.create_ellipse(cs_plane='Z', position=[0,0,0],
... major_radius=2, ratio=2, is_covered=True, name="myell",
... matname="vacuum")


"""
szAxis = GeometryOperators.cs_plane_to_axis_str(cs_plane)
XStart, YStart, ZStart = self._pos_with_arg(position)
Expand Down Expand Up @@ -833,6 +912,28 @@ def create_equationbased_curve(

>>> oEditor.CreateEquationCurve


Examples
--------
The following examples shows how to create an equation based curve in HFSS.
The main parameters are ``cs_plane`` that provides the plane on which the ellipse is designed,
``position`` that provides the origin of the ellipse, ``major_radius`` of the ellipse,
``ratio`` between major radius and minor radius of the ellipse,
``is_covered`` a flag to determine if ellipse is covered or no.
The parameter ``matname`` is optional and allows to set the material name of the ellipse.
The parameter ``name`` is optional and allows to give a name to the ellipse.
This method applies to all 3D applications: HFSS, Q3D, Icepak, Maxwell 3D, Mechanical.

>>> from pyaedt import Hfss
>>> aedtapp = Hfss()
>>> eq_xsection = self.aedtapp.modeler.create_equationbased_curve(x_t="_t",
... y_t="_t*2",
... num_points=200,
... z_t=0,
... t_start=0.2,
... t_end=1.2,
... xsection_type="Circle")

"""
x_section = self._crosssection_arguments(
type=xsection_type,
Expand Down Expand Up @@ -913,6 +1014,32 @@ def create_helix(

>>> oEditor.CreateHelix

Examples
--------
The following example shows how to create a polyline and then create an helix from the polyline.
This method applies to all 3D applications: HFSS, Q3D, Icepak, Maxwell 3D, Mechanical.

>>> from pyaedt import Hfss
>>> aedtapp = Hfss()
>>> udp1 = [0, 0, 0]
>>> udp2 = [5, 0, 0]
>>> udp3 = [10, 5, 0]
>>> udp4 = [15, 3, 0]
>>> polyline = aedtapp.modeler.create_polyline(
>>> [udp1, udp2, udp3, udp4], cover_surface=False, name="helix_polyline"
>>> )

>>> helix_right_turn = aedtapp.modeler.create_helix(
>>> polyline_name=polyline.name,
>>> position=[0, 0, 0],
>>> x_start_dir=0,
>>> y_start_dir=1.0,
>>> z_start_dir=1.0,
>>> num_thread=1,
>>> right_hand=True,
>>> radius_increment=0.0,
>>> thread=1.0,
>>> )
"""
if not polyline_name or polyline_name == "":
raise ValueError("The name of the polyline cannot be an empty string.")
Expand Down Expand Up @@ -958,7 +1085,7 @@ def convert_segments_to_line(self, object_name):

Parameters
----------
object_name : int, str, or Object3d
object_name : int, str, or :class:`pyaedt.modeler.cad.object3d.Object3d`
Specified for the object.

Returns
Expand All @@ -971,6 +1098,15 @@ def convert_segments_to_line(self, object_name):

>>> oEditor.ChangeProperty

Examples
--------

>>> from pyaedt import Hfss
>>> aedtapp = Hfss()
>>> edge_object = aedtapp.modeler.create_object_from_edge("my_edge")
>>> aedtapp.modeler.generate_object_history(edge_object)
>>> aedtapp.modeler.convert_segments_to_line(edge_object.name)

"""
this_object = self._resolve_object(object_name)
edges = this_object.edges
Expand Down