.. admonition:: Work in Progress
   :class: warning

   This document is still under development and may change frequently.

=====================
Excitation Coil Model
=====================

.. toctree::
   :maxdepth: 2
   :caption: Excitation Coil
   :hidden:
   
   stranded_coil
   open_coil
   closed_coil
   excitation_current

Excitation coils are widely used in electromagnetic applications such as motors, transformers, and inductors
to generate magnetic fields. 


.. list-table:: Examples of Excitation Coils used in Electromagnetic Applications
   :widths: 33 33 33
   :header-rows: 0

   * - .. figure:: images/transformer.png
        :align: center
        :width: 80%
     - .. figure:: images/Transformer.png
        :align: center
        :width: 80%
     - .. figure:: images/ActuatorCoil.png
        :align: center
        :width: 80%
   * - A primary and secondary (wound) excitation coil in a transformer. Only half is shown due to usage of a symmetry plane
     - A transformer with a primary and secondary coil. Both coils are a thin wire wound many times around a core.
       (image credit: `CC BY-SA 4.0 <https://en.wikipedia.org/wiki/Transformer#/media/File:Philips_N4422_-_power_supply_transformer-2098.jpg>`_)
     - A solenoid coil used in an actuator. The coil is wound around a core and generates a magnetic field when a current is applied.
       (image credit: `CC BY-SA 3.0 <https://commons.wikimedia.org/wiki/File:Canon_AF-10_Date_old_camera_shutter_driver_coil..jpg>`_)


This model here allows the setup of various type of excitation coils and their excitation based on predefined
parameters.

To add an excitation coil to simulation use first add the `ExcitationCoilModel` using:

.. testsetup::

  import mufem
  from mufem import Vol

  sim = mufem.Simulation.New("My Case", f"data/geometry.mesh")

  my_coil_marker = "MyVolume" @ Vol

.. testcode::

  from mufem.electromagnetics.coil import ExcitationCoilModel

  coil_model = ExcitationCoilModel()
  sim.get_model_manager().add_model(coil_model)




Then use `CoilSpecification` to describe the properties of each individual coil.
A coil specification requires the specification of a  :ref:`coil type<coil type>`,
a :ref:`coil topology<coil topology>`, and a :ref:`coil excitation<coil excitation>`.
Finally, add it to the model:

.. testsetup::

  from mufem.electromagnetics.coil import ExcitationCoilModel

  coil_model = ExcitationCoilModel()
  sim.get_model_manager().add_model(coil_model)

  

.. testcode::

  # from mufem.electromagnetics.coil import CoilSpecification

  # coil = CoilSpecification(
  #           name="Coil", marker=my_coil_marker, topology=my_coil_topology, type=my_coil_type, excitation=my_coil_excitation
  #)
  #coil_model.add_coil_specification(coil)


.. _coil type:

Coil Type
---------

The following coil types are available for the time-domain magnetic model:


.. list-table:: Supported Coil Types
   :widths: 15 50 35
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - :doc:`Stranded coil <stranded_coil>` 
     - * Does not model individual strands but combines them to a single homogenized region.
       * Applicable when the individual wires have a small diameter compared to the skin depth of the material
         otherwise modelling errors are introduced such as an underestimation of losses (AC losses).

     -   
       .. figure:: images/StrandedCoilHomogenization2.png
          :align: center
          :width: 100%

          Instead of modelling individual wire the coil is homogenized to a single body.

.. _coil topology:

Coil Topology
-------------

.. list-table:: Supported Coil Topologies
   :widths: 15 50 35
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - :doc:`Open coil <open_coil>` 
     - The coil is open, and the current enters and leaves the coil through boundary faces.
     - .. figure:: images/OpenCoil.png
          :align: center
          :width: 100%

          Example of an open coil with two boundaries.
          
   * - :doc:`Closed coil <closed_coil>` 
     - The coil is closed, and the current circulates through the coil.   
     - .. figure:: images/ClosedCoil.png
          :align: center
          :width: 100%
          
          Example of a closed coil.


.. _coil excitation:

Coil Excitation
---------------

.. list-table:: Supported Coil Excitations
   :widths: 15 50 35
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - :doc:`Current Excitation <excitation_current>` 
     - The coil is excited through a current source.
     - .. figure:: images/current_circuit.png
          :align: center
          :width: 100%

          An excitation coil excited through a current source.



Reports
-------

Following reports are available for the time-domain magnetic model for visualization:

.. list-table:: List of reports
   :widths: 35 15 50
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - Coil Current Report
     - Scalar Value
     - Returns the applied current to the coil
   * - Coil Resistance Report
     - Scalar Value
     - Returns the resistance of the coil
   * - Flux Linkage Report
     - Scalar Value
     - Returns the flux linkage of the coil
   * - Inductance Report
     - Symmetric Matrix
     - Returns the inductance of the coil

Coefficient Functions
---------------------

Following functions are available for the time-domain magnetic model for visualization:

.. list-table:: List of functions
   :widths: 25 25 50
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - Flux Linkage
     - Scalar Field
     - The magnetic flux linkage function is defined as:

       .. math::

         \psi = \mathbf{A} \cdot \mathbf{\tau}

   * - Electromotive Force
     - Scalar Field
     - The electromotive force function is defined as:

       .. math::

         \mathcal{E} = \dot{\mathbf{A}} \cdot \mathbf{\tau}