==================
Usage and Examples
==================
This module is very basic, mainly involving the :ref:`VolumeMesh` class.
The usage of this libary will be illustrated through examples, and further details
can be found in the other sections. The full examples are given in the `samples <https://git.acem.ece.illinois.edu/kjao/Geometry/src/branch/main/samples>`__ folder.
We show the examples in Python, but as the module is built from C++, it should be a direct
translation if needed. Refer to :doc:`classes` for more information.


Mesh Structure
==============
The mesh is composed of three main parts: vertices, elements, and marked faces.
We group elements and marked faces with element and face sets, respectively. We may want to
assign attributes or conditions onto these element or face sets. This is accomplished by
creating a JSON file. For example,

.. code-block:: json

    {
        "Element Sets": [
            {
                "index": 0,
                "attribute": "air"
            }
        ],
        "Face Sets": [
            {
                "index": 0,
                "boundary": "PEC"
            },
            {
                "index": 1,
                "boundary": "ABC"
            }
        ],
        "Hybrid Mesh": {
            "enable": true,
            "holes": [
                [0, 0, 0], [7, -7, 0]
            ]
        }
    }

These three main sections *must* be present in the JSON file for it to be read properly.
Currently, the supported boundary conditions are

* [0] PEC (Perfect Electric Conductor)
* [1] PMC (Perfect Magnetic Conductor)
* [2] ABC (Absorbing Boundary Condition)
* [3] PML (Perfectly Matched Layer)
* [4] None
* [5] None
* [6] None
* [7] NCB (Perfect Magnetic Conductor)

Loading
=======
This example shows how to load a EXODUS (.g) mesh file and access its information.

.. code-block:: python

    import Geometry as geo

    mesh_path = "../mesh/Cylinder.g"
    json_path = "../mesh/Cylinder.json"

    mesh = geo.VolumeMesh.from_exodus(mesh_path)
    mesh.apply_config(json_path)
    print(mesh.info)
    print()

    print("Vertex Array:")
    print(mesh.vertices)
    print()

    print("Vertex Indices of Element Set 0:")
    print(mesh.elem_set(0))
    print()

    print("Face Indices of Face Set 0:")
    print(mesh.face_set(0))
    print()

    print("Element Operations:")
    elem = mesh.element(0)
    print("Volume:", elem.volume())
    for face_num in range(4):
        print(f"Face {face_num}:")
        print(elem.face(face_num))
        print("Area:", elem.face(face_num).normal().norm() / 2)
    print()

    print("Element Set 0 Attribute:", mesh.get_elem_set_attribute(0))
    print("Face Set 0 Boundary Condition:",  mesh.get_face_set_bc(0))
    print()


Exporting STLs
==============
Following from there, we can also export mesh data. We can export all the elements
as faces, or specific face sets.

.. code-block:: python

    BC = geo.BoundaryCondition # Shorthand

    mesh.save_exodus("CylinderVolume") # Export EXODUS (.g) file.
    mesh.extract_surfaces().save_stl("CylinderBoundary") # Export STL file.
    # Only export the ABC Boundary.
    mesh.extract_surfaces(mesh.face_sets_with_bc(BC.ABC)).save_stl("CylinderABC")

Hybrid Mesh Generation
======================
To utilize the hybrid mesh generation functionality, we need only
call a few functions.

.. code-block:: python

    mesh = geo.VolumeMesh.from_exodus(mesh_path)
    config = mesh.apply_config(json_path) # Get the config data.

    BC = geo.BoundaryCondition # Shorthand

    # Generate the grid mesh with each cube's side being 1.4.
    # Ignore ABC face sets when generating the regular mesh.
    hybrid = mesh.create_hybrid_mesh(1.4, mesh.face_sets_with_bc(BC.ABC))
    hybrid.export_exodus("HybridCylinder")

    hybrid_surfs = hybrid.extractSurfaces()
    hybrid_surfs.save_stl("InnerCylinderPEC", inner.face_sets_with_bc(BC.PEC))
    hybrid_surfs.save_stl("InnerCylinderNCB", inner.face_sets_with_bc(BC.NCB))