.. _api_reference:

API Reference
=============

This document provides a detailed API reference for the classes and methods in the ``em-app`` package.

``solvers.py``
--------------

This module contains functions for calculating the magnetic field using the Biot-Savart law.

.. list-table::
   :widths: 15 25 45 15
   :header-rows: 1

   * - Function
     - Description
     - Arguments
     - Returns
   * - ``serial_biot_savart``
     - Serial Biot-Savart calculation with element inputs.
     - - ``element_centers`` (numpy.ndarray): (N, 3) array of center coordinates.
       - ``element_lengths`` (numpy.ndarray): (N,) array of lengths (dl).
       - ``element_directions`` (numpy.ndarray): (N, 3) array of unit vectors for current directions.
       - ``field_points`` (numpy.ndarray): (M, 3) array of field point coordinates.
       - ``order`` (int, optional): Max order of Taylor series.
       - ``backend`` (str, optional): Backend to use ('python', 'cpp', etc.).
     - ``numpy.ndarray``: (M, 3) array of magnetic field vectors.
   * - ``mpi_biot_savart``
     - Parallel Biot-Savart calculation using mpi4py.
     - - (Same as ``serial_biot_savart``)
     - ``numpy.ndarray`` or ``None``: On MPI rank 0, an (M, 3) array. On other ranks, ``None``.
   * - ``numpy_biot_savart``
     - NumPy vectorized Biot-Savart calculation.
     - - (Same as ``serial_biot_savart``)
     - ``numpy.ndarray``: (M, 3) array of magnetic field vectors.
   * - ``calculate_b_field``
     - Calculates the magnetic field generated by a coil.
     - - ``coil_instance`` (Coil): An instance of a Coil subclass.
       - ``field_points`` (np.ndarray): The points where the magnetic field should be calculated.
       - ``backend`` (str, optional): The backend to use.
     - ``Bfield``: A ``Bfield`` object containing the calculated magnetic field.

``sources.py``
--------------

This module defines classes for representing different current-carrying coil geometries.

``Coil`` Class
~~~~~~~~~~~~~~

Base class for a current-carrying coil.

.. rubric:: Attributes

.. list-table::
   :widths: 25 15 60
   :header-rows: 1

   * - Attribute
     - Type
     - Description
   * - ``current``
     - ``float`` or ``mtf``
     - The current flowing through the coil.
   * - ``use_mtf_for_segments``
     - ``bool``
     - Whether to use MTF for representing the coil segments.
   * - ``wire_thickness``
     - ``float``
     - The thickness of the wire in meters.
   * - ``segment_centers``
     - ``np.ndarray``
     - Array of the center points of the coil segments.
   * - ``segment_lengths``
     - ``np.ndarray``
     - Array of the lengths of the coil segments.
   * - ``segment_directions``
     - ``np.ndarray``
     - Array of the direction vectors of the coil segments.

.. rubric:: Methods

.. list-table::
   :widths: 20 50 30
   :header-rows: 1

   * - Method
     - Description
     - Returns
   * - ``get_segments``
     - Returns the discretized segments of the coil.
     - ``tuple``: (segment_centers, segment_lengths, segment_directions)
   * - ``get_max_size``
     - Calculates the maximum extent of the coil.
     - ``np.ndarray``: (3,) array of the maximum size.
   * - ``get_center_point``
     - Calculates the approximate center point of the coil.
     - ``np.ndarray``: (3,) array representing the center.
   * - ``plot``
     - Plots the coil segments in 3D. (Requires matplotlib)
     - ``None``

``RingCoil`` Class
~~~~~~~~~~~~~~~~~~

Represents a circular current-carrying coil. Inherits from ``Coil``.

.. rubric:: Attributes

.. list-table::
   :widths: 25 15 60
   :header-rows: 1

   * - Attribute
     - Type
     - Description
   * - ``radius``
     - ``float``
     - Radius of the coil.
   * - ``num_segments``
     - ``int``
     - Number of segments for discretization.
   * - ``center_point``
     - ``np.ndarray``
     - (3,) array for the center coordinates.
   * - ``axis_direction``
     - ``np.ndarray``
     - (3,) array for the axis direction.

``RectangularCoil`` Class
~~~~~~~~~~~~~~~~~~~~~~~~~

Represents a rectangular current-carrying coil. Inherits from ``Coil``.

``StraightWire`` Class
~~~~~~~~~~~~~~~~~~~~~~

Represents a single straight current-carrying wire. Inherits from ``Coil``.

.. rubric:: Attributes

.. list-table::
   :widths: 25 15 60
   :header-rows: 1

   * - Attribute
     - Type
     - Description
   * - ``start_point``
     - ``np.ndarray``
     - The starting point of the wire.
   * - ``end_point``
     - ``np.ndarray``
     - The ending point of the wire.

``plotting.py``
---------------

This module contains functions for plotting magnetic field data.

.. list-table::
   :widths: 20 30 50
   :header-rows: 1

   * - Function
     - Description
     - Key Arguments
   * - ``plot_1d_field``
     - Plots a magnetic field component along a 1D line.
     - ``coil_instance``, ``field_component``, ``axis``, ``start_point``, ``end_point``
   * - ``plot_2d_field``
     - Plots a magnetic field on a 2D plane.
     - ``coil_instance``, ``field_component``, ``plane``, ``center``
   * - ``plot_field_vectors_3d``
     - Generates a 3D quiver plot of the magnetic field vectors.
     - ``coil_instance``, ``num_points_a``, ``num_points_b``, ``num_points_c``

``vector_fields.py``
--------------------

This module defines classes for representing and manipulating vector field data.

``Vector`` Class
~~~~~~~~~~~~~~~~

A generic class to represent a 3D vector.

.. rubric:: Methods

.. list-table::
   :widths: 20 50 30
   :header-rows: 1

   * - Method
     - Description
     - Returns
   * - ``dot``
     - Calculates the dot product with another Vector.
     - ``mtf`` or ``float``
   * - ``cross``
     - Calculates the cross product with another Vector.
     - ``Vector``
   * - ``norm``
     - Calculates the magnitude (L2-norm) of the vector.
     - ``float`` or ``mtf``
   * - ``to_numpy_array``
     - Converts the vector to a NumPy array.
     - ``np.ndarray``

``Bvec`` Class
~~~~~~~~~~~~~~

Represents the magnetic field vector at a point. Inherits from ``Vector``.

.. rubric:: Methods

.. list-table::
   :widths: 20 50 30
   :header-rows: 1

   * - Method
     - Description
     - Returns
   * - ``curl``
     - Calculates the curl of the B-field vector.
     - ``Bvec``
   * - ``divergence``
     - Calculates the divergence of the B-field.
     - ``mtf``
   * - ``gradient``
     - Calculates the Jacobian matrix of the B-field vector.
     - ``np.ndarray`` (3x3 array of MTFs)

``VectorField`` Class
~~~~~~~~~~~~~~~~~~~~~

A class to store a collection of vectors at different points in space.

.. rubric:: Attributes

.. list-table::
   :widths: 25 15 60
   :header-rows: 1

   * - Attribute
     - Type
     - Description
   * - ``vectors``
     - ``np.ndarray``
     - A NumPy array of ``Vector`` objects.
   * - ``field_points``
     - ``np.ndarray``
     - A corresponding (N, 3) NumPy array of points.

.. rubric:: Methods

.. list-table::
   :widths: 20 50 30
   :header-rows: 1

   * - Method
     - Description
     - Returns
   * - ``get_magnitude``
     - Calculates the magnitude of each vector.
     - ``np.ndarray``
   * - ``to_dataframe``
     - Exports the field to a pandas DataFrame.
     - ``pandas.DataFrame``