Integrator::Mechanics
=====================

:bdg-link-secondary-line:`src/Integrator/Mechanics.H <../../doxygen/Mechanics_8H_source.html>`

This is a general purpose integrator that focuses on solving 
elasticity/mechanics equations in the absence of other multiphysics
simulations.
It is enabled by :code:`alamo.program=mechanics` if used on its own, in
which case there is no prefix.
If it is being used by another integrator, see that integrator to determine
the value of :code:`[prefix]` (often equal to :code:`elastic`).

This integrator inherits from :ref:`Integrator::Base::Mechanics`; see 
documentation for that integrator for additional parameters.

:bdg-primary-line:`Model setup`
There are two basic tools for setting up a mechanics problem in this
integrator.

1. The :code:`eta` field: this is used to mix models of different types.
   Use :code:`nmodels` to specify how many material models to use, and then
   specify each model as :code:`model1`, :code:`model2`, etc.
   The type of moel is specified using the :code:`alamo.program.mechanics.model`
   input.

   Once you have done this, you must determine the spatial distribution of each
   model. This is done by choosing an IC for the eta field with :code:`ic.type`.
   The :code:`IC::Expression` is the most general and recommended.
   The models are then mixed linearly, i.e.

   .. math::

      W_{\textrm{eff}} = \sum_{i=1}^N W_i\,\eta_i(\mathbf{x})

   See the :ref:`Eshelby` test for an example of model mixing.

2. The :code:`psi` field: this is used specifically for cases where a "void" region
   is desired. Its usage is similar to the :code:`eta` case, and is conceptually
   similar in that it scales the model field to near-zero in order to mimic the
   (lack of) mechanical behavior in an empty region.
   It is important to use :code:`psi` here, for reasons that are discussed in detail
   in
   `this paper <https://doi.org/10.1007/s00466-023-02325-8>`__.
   The initialization of :code:`psi` is similar to that for :code:`eta`.
   
   See the :ref:`PlateHole` and :ref:`RubberPlateHole` for canonical exmaples.
   The :ref:`Integrator::Fracture` and :ref:`Integrator::TopOp` integrators are examples
   of integrators that leverage the psi property.

:bdg-primary-line:`Body forces` 
currently have limited support due to the relatively low number of 
times they are needed. See the :ref:`Integrator::Base::Mechanics` documentation for 
detail. 
See the :ref:`TrigTest` test for examples of current body force implementation.

:bdg-primary-line:`Boundary conditions` 
are implemented using the :ref:`BC::Operator::Elastic` classes.
See the documentation on these classes for more detail.
See any of the mechanics-based tests for examples of boundary condition application.

.. raw:: html

   <div class="input-reference-list">
     <article class="input-reference-item" id="input-nmodels-7d361fa0e9">
       <header class="input-reference-item-header">
         <a class="input-reference-name" href="../../doxygen/Mechanics_8H_source.html#l00128"><code>nmodels</code></a>
         <div class="input-reference-badges"><span class="input-reference-badge input-reference-badge-default">1</span> <span class="input-reference-badge input-reference-badge-meta">conditional</span></div>
       </header>
       <p class="input-reference-description">Number of elastic model varieties</p>
       <details class="input-reference-resolved">
         <summary>Names by executable <span>4 executables, 4 uses</span></summary>
         <div class="input-reference-resolved-body">
           <div class="input-reference-executable">
             <strong>mechanics-2d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>nmodels</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>mechanics-3d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>nmodels</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>thermoelastic-2d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>el.nmodels</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>thermoelastic-3d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>el.nmodels</code>
             </div>
           </div>
         </div>
       </details>
     </article>
     <article class="input-reference-item" id="input-model-f26bf5c2f9">
       <header class="input-reference-item-header">
         <a class="input-reference-name" href="../../doxygen/Mechanics_8H_source.html#l00130"><code>model</code></a>
         <div class="input-reference-badges"><span class="input-reference-badge input-reference-badge-meta">repeatable</span> <span class="input-reference-badge input-reference-badge-meta">conditional</span></div>
       </header>
       <p class="input-reference-description"><em>No documentation available.</em></p>
       <details class="input-reference-resolved">
         <summary>Names by executable <span>4 executables, 4 uses</span></summary>
         <div class="input-reference-resolved-body">
           <div class="input-reference-executable">
             <strong>mechanics-2d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>model</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>mechanics-3d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>model</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>thermoelastic-2d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>el.model</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>thermoelastic-3d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>el.model</code>
             </div>
           </div>
         </div>
       </details>
     </article>
     <article class="input-reference-item" id="input-eta-ref-threshold-c63bdd706e">
       <header class="input-reference-item-header">
         <a class="input-reference-name" href="../../doxygen/Mechanics_8H_source.html#l00134"><code>eta_ref_threshold</code></a>
         <div class="input-reference-badges"><span class="input-reference-badge input-reference-badge-default">0.01</span> <span class="input-reference-badge input-reference-badge-meta">conditional</span></div>
       </header>
       <p class="input-reference-description">Refinement threshold for eta field</p>
       <details class="input-reference-resolved">
         <summary>Names by executable <span>4 executables, 4 uses</span></summary>
         <div class="input-reference-resolved-body">
           <div class="input-reference-executable">
             <strong>mechanics-2d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>eta_ref_threshold</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>mechanics-3d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>eta_ref_threshold</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>thermoelastic-2d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>el.eta_ref_threshold</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>thermoelastic-3d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>el.eta_ref_threshold</code>
             </div>
           </div>
         </div>
       </details>
     </article>
     <article class="input-reference-item" id="input-ref-threshold-7d0803fc94">
       <header class="input-reference-item-header">
         <a class="input-reference-name" href="../../doxygen/Mechanics_8H_source.html#l00136"><code>ref_threshold</code></a>
         <div class="input-reference-badges"><span class="input-reference-badge input-reference-badge-default">0.01</span> <span class="input-reference-badge input-reference-badge-meta">conditional</span></div>
       </header>
       <p class="input-reference-description">Refinement threshold for strain gradient</p>
       <details class="input-reference-resolved">
         <summary>Names by executable <span>4 executables, 4 uses</span></summary>
         <div class="input-reference-resolved-body">
           <div class="input-reference-executable">
             <strong>mechanics-2d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>ref_threshold</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>mechanics-3d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>ref_threshold</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>thermoelastic-2d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>el.ref_threshold</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>thermoelastic-3d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>el.ref_threshold</code>
             </div>
           </div>
         </div>
       </details>
     </article>
     <article class="input-reference-item" id="input-model-neumann-boundary-b27b8badb2">
       <header class="input-reference-item-header">
         <a class="input-reference-name" href="../../doxygen/Mechanics_8H_source.html#l00138"><code>model_neumann_boundary</code></a>
         <div class="input-reference-badges"><span class="input-reference-badge input-reference-badge-default">0</span> <span class="input-reference-badge input-reference-badge-option">1</span> <span class="input-reference-badge input-reference-badge-meta">conditional</span></div>
       </header>
       <p class="input-reference-description">Explicity impose neumann condition on model at domain boundaries (2d only)</p>
       <details class="input-reference-resolved">
         <summary>Names by executable <span>4 executables, 4 uses</span></summary>
         <div class="input-reference-resolved-body">
           <div class="input-reference-executable">
             <strong>mechanics-2d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>model_neumann_boundary</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>mechanics-3d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>model_neumann_boundary</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>thermoelastic-2d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>el.model_neumann_boundary</code>
             </div>
           </div>
           <div class="input-reference-executable">
             <strong>thermoelastic-3d-coverage-g++</strong>
             <div class="input-reference-paths">
               <code>el.model_neumann_boundary</code>
             </div>
           </div>
         </div>
       </details>
     </article>
   </div>