Tutorial 1: UCS model from Gmsh
#######################################

This example will review how to setup a uniaxial compressive test example with output from Gmsh software. 

**Runtime**: <10 min on i9 8-core Windows 10 Machine

Expected tutorial result: 

.. image:: ../../images/ucs_example.png
  :width: 800
  :alt: UCS Example Image

OpenFDEM supports four main mesh pre-processing approaches:
1. A user defined command in OpenFDEM to create mesh automatically
2. Importing a ``.geo`` file
3. Importing a ``.msh`` file 
4. Mesh developed from other commercial softwares, including ``.inp``, ``.dxf``, ``.fdem``, 
``.tess`` (for grain-based model only) and ``.jpg`` (for grain-based module and DFN module only).

Tutorial Prerequistes
****************************************************
The following files are needed to follow along the tutorial:

- `example_UCS.geo`_ (click to download from Gitlab)
- `example_UCS.msh`_ (click to download from Gitlab)

.. _example_UCS.geo: http://geogroup.utoronto.ca:9191/gitlab/xiaofeng.li/openfdem_solver/-/blob/main/openfdem%20src/src/test/UCS%20by%20gmsh/example_UCS.geo
.. _example_UCS.msh: http://geogroup.utoronto.ca:9191/gitlab/xiaofeng.li/openfdem_solver/-/blob/main/openfdem%20src/src/test/UCS%20by%20gmsh/example_UCS.msh

Tutorial Steps
****************************************************

OpenFDEM tutorials have the same main steps:

1. Mesh pre-processing steps.
2. Materials definition.
3. Define boundary conditions.
4. Specify the outputs.

A ``.log`` file is auto-generated by default in the same folder as the input file. To disable the logging, specify this 
line into the input file::

	of.debug off 

Step 1. Mesh Pre-processing
============================

Create a new empty text file (later add the `.of` extension). Begin writing the following commands:

.. literalinclude:: ../../../src/test/UCS by gmsh/UCS_from geo.of
   :lines: 24

You can create mesh based on the built-in command lines, OpenFDEM supports to create ``retangular``, ``circle``, ``ellipse``, 
``arbitary polygon`` from table, ``geometrical rigid wall``, ``particle`` and ``material points``. The bool operators support 
``intersection``, ``union``, ``difference`` and ``fragment`` between different entities. 

.. literalinclude:: ../../../src/test/UCS by gmsh/UCS_from geo.of
   :lines: 26-28
   
.. literalinclude:: ../../../src/test/UCS by gmsh/UCS_from geo.of
   :lines: 29-30

.. literalinclude:: ../../../src/test/UCS by gmsh/UCS_from geo.of
   :lines: 31-32

.. literalinclude:: ../../../src/test/UCS by gmsh/UCS_from geo.of
   :lines: 33-34

After creating geometry entities, you can assign mesh size to the whole model with ``all`` keyword and it is also possible to assign
mesh size to specific entities:

.. literalinclude:: ../../../src/test/UCS by gmsh/UCS_from geo.of
   :lines: 36-41
   
``OpenFDEM`` will call the Gmsh kernel to generate mesh after the mesh size is assigned. The meshing scheme includes ``delaunay`` (default),
``meshadapt`` and ``frontal-delaunay`` . The gmsh interface will be called and you can check the mesh quality, recombine the mesh or change mesh size in gmsh pannel.
   
.. literalinclude:: ../../../src/test/UCS by gmsh/UCS_from geo.of
   :lines: 43-44

Cohesive elements can be inserted after importing the mesh. The kernel will call FEM solver only when no cohesive elements are inserted, and the DEM solver will be called
as the mesh is splitted by ``of.mesh.split``. OpenFDEM supports to partially insert cohesive elements and also supports inserting extrinsic cohesive elements.
 
.. literalinclude:: ../../../src/test/UCS by gmsh/UCS_from geo.of
   :lines: 46-47
   
Step 2. Materials Definition
==============================
Material parameters contain three parts, the parameter for solid matrix, solid cohesive element and contacts. The paramters will be allocated to the user-defined element groups,
the material parameters can be found in the materials library. 

.. literalinclude:: ../../../src/test/UCS by gmsh/UCS_from geo.of
  :lines: 49-59

Step 3. Define Boundary Conditions
===================================
The boundary conditions are defined by the entity groups. It has body gravity on nodes, velocity, initial velocity, force, absorbing and acceleration boundaries on nodes,
and normal pressure, shear pressure boundaries on edges. It is also aviable to apply boundaries in local coords.

.. literalinclude:: ../../../src/test/UCS by gmsh/UCS_from geo.of
   :lines: 61-69

Step 4. Post-Processing Settings
==================================
The post-processing can export field results in format of ``.vtk``, ``.vtp``, ``.vtu``, and Tecplot supported format. It also supports to monitor
variables on the specific entity at every step. 

.. literalinclude:: ../../../src/test/UCS by gmsh/UCS_from geo.of
   :lines: 75-82

Step 5. Run models
=============================

Finally, define the number of time-steps:

.. literalinclude::  ../../../src/test/UCS by gmsh/UCS_from geo.of
   :lines: 89-90

Full Tutorial Script
=======================

To run the model, save your text file with the `.of` extension. Rebuild the openfdem solution and drag your
`.of` file into the `OpenFDEM.exe`. It will automatically run and save the outputs. 

Complete script below:

.. include:: ../../../src/test/UCS by gmsh/UCS_from geo.of
    :literal: