Feat/Adding extended examples library. (#613)

* Added index.

Added ex 01.

Resolves #612
Resolves #567

* Fixing grammar

* Fixing grammar

* Fixing format

* Format fixing.

* Format fixing

* Renaming files to keep conventions.

* Space format fixing

* Format fixing

* Small changes

* Added more info to the examples.

* Apply suggestions from code review

Approved review changes made by @alex

Co-authored-by: Alex Kaszynski <[email protected]>

* Small format fix.

Co-authored-by: Alex Kaszynski <[email protected]>

Author: germa89

doc/source/user_guide/extended_examples/ex_01-gmsh_example/ex_01-gmsh_example.rst

@@ -0,0 +1,71 @@
+.. _extended_example01:
+
+
+Example 01: Gmsh Example
+========================
+
+Objective
+---------
+Demonstrate the interoperability of PyAnsys with ``gmsh``, a very well known
+open source Python meshing library.
+
+For more information about ``gmsh`` please visit its website: `Gmsh <https://gmsh.info/>`_.
+
+Description
+-----------
+In this example the interoperability of PyAnsys with the open source mesher ``gmsh`` is demonstrated.
+Using ``gmsh`` we import an external geometry file in STL format and then the 
+geometry is imported into PyMAPDL using the 
+`pymapdl-reader <https://github.com/pyansys/pymapdl-reader>`_ library.
+
+This example is composed of several files. 
+
+* ``gmsh_converter.py``: Load a STEP file, mesh it, and save it as a gmsh file. 
+* ``mesh_converter``: Convert the ``*.msh`` file into an Ansys CDB database format file (archive file). 
+* ``modal_analysis.py``: Import CDB database, setup the modal analysis and run
+  it. It also shows an animation of the first mode and save it
+  to a gif file named ``animation.gif``. 
+
+
+Requirements
+------------
+You need to have ``gmsh`` installed. You can install it using ``pip``:
+
+.. code-block:: 
+
+    pip install gmsh
+
+
+Source code
+-----------
+
+``gmsh_generator.py``
+~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: gmsh_generator.py
+    :linenos:
+    :language: python
+
+
+``mesh_converter.py``
+~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: mesh_converter.py
+    :linenos:
+    :language: python
+
+
+``modal_analysis.py``
+~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: modal_analysis.py
+    :linenos:
+    :language: python
+
+
+
+Notes
+-----
+
+It is recommended that you copy all the files in a separate directory to make it
+easier to run the example. 

doc/source/user_guide/extended_examples/ex_01-gmsh_example/gmsh_generator.py

@@ -0,0 +1,24 @@
+"""Using ``gmsh`` read the STEP file, mesh it, and save it as a ``*.msh`` file."""
+import gmsh
+
+gmsh.initialize()
+gmsh.option.setNumber("General.Terminal", 1)
+
+gmsh.model.add("t20")
+
+# Load a STEP file (using `importShapes' instead of `merge' allows to directly
+# retrieve the tags of the highest dimensional imported entities):
+filename = 'pf_coil_case_1.stp'
+v = gmsh.model.occ.importShapes(filename)
+
+
+# Get the bounding box of the volume:
+gmsh.model.occ.synchronize()
+
+# Specify a global mesh size and mesh the partitioned model:
+gmsh.option.setNumber("Mesh.CharacteristicLengthMin", 10)
+gmsh.option.setNumber("Mesh.CharacteristicLengthMax", 10)
+gmsh.model.mesh.generate(3)
+gmsh.write("from_gmsh.msh")
+
+gmsh.finalize()

doc/source/user_guide/extended_examples/ex_01-gmsh_example/mesh_converter.py

@@ -0,0 +1,12 @@
+"""
+This script convert the file in `gmsh` format to ANSYS `CDB` format.
+"""
+
+import pyvista as pv
+from ansys.mapdl.reader import save_as_archive
+
+filename = 'from_gmsh.msh'
+mesh = pv.read_meshio(filename)
+# mesh.plot()  # optionally plot the mesh
+mesh.points /= 1000
+save_as_archive('archive.cdb', mesh)

doc/source/user_guide/extended_examples/ex_01-gmsh_example/modal_analysis.py

@@ -0,0 +1,63 @@
+"""Import the CDB database, setup modal analysis and run it."""
+
+
+from ansys.mapdl.core import launch_mapdl
+
+mapdl = launch_mapdl(override=True, additional_switches="-smp")
+filename = "archive.cdb"
+mapdl.cdread("db", filename)
+mapdl.save()
+
+# verify cells are valid
+mapdl.prep7()
+mapdl.shpp("SUMM")
+
+# specify material properties
+# using aprox values for AISI 5000 Series Steel
+mapdl.units("SI")
+mapdl.mp("EX", 1, 200e9)  # Elastic moduli in Pa (kg/(m*s**2))
+mapdl.mp("DENS", 1, 7700)  # Density in kg/m3
+mapdl.mp("NUXY", 1, 0.3)  # Poissons Ratio
+mapdl.et(1, 181)  # ! ET,1,SHELL181 ! SHELL181
+mapdl.keyopt(
+    1, 3, 2
+)  # ! Option for the shell. Integration option: 'Full integration with incompatible modes'
+mapdl.sectype(1, "SHELL")
+mapdl.secdata(1, 1, 0, 3)  # ! which means: SECDATA,TK, MAT, THETA, NUMPT, LayerName
+mapdl.emodif("ALL", "MAT", 1)  # ! Setting material id
+mapdl.emodif("ALL", "REAL", 1)  # ! Setting real constant
+
+# By setting the section type (`SECTYPE`) the model will run and solve.
+
+# The model has solid and shell elements.
+# We don't need both, hence I'm going to delete the shell elements.
+mapdl.esel("S", "type", "", 4)  # selecting elements with type 4 = shell181
+mapdl.edele("all")
+mapdl.allsel()
+
+# Run an unconstrained modal analysis
+mapdl.run("/SOLU")
+mapdl.outres("all")
+mapdl.antype("MODAL")  # default NEW
+mapdl.modopt("LANB", 20, 1)
+mapdl.solve(verbose=False)
+mapdl.save("solved")
+
+mapdl.post1()
+mapdl.set("FIRST")
+
+result = mapdl.result
+
+result.animate_nodal_displacement(
+    4,
+    show_edges=False,
+    lighting=True,
+    loop=True,
+    add_text=False,
+    nangles=30,
+    # displacement_factor=50,
+    n_frames=100,
+    movie_filename="animation.gif",
+)
+
+mapdl.exit()