FEM4EllipticPDE/include/LinearMag.h

/* This file is part of Lemma, a geophysical modelling and inversion API.
 * More information is available at http://lemmasoftware.org
 */

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 */

/**
 * @file
 * @date      03/21/2016 01:39:32 PM
 * @version   $Id$
 * @author    Trevor Irons (ti)
 * @email     tirons@egi.utah.edu
 * @copyright Copyright (c) 2016, University of Utah
 * @copyright Copyright (c) 2016, Lemma Software, LLC
 */

#ifndef  LINEARMAG_INC
#define  LINEARMAG_INC

#include  <vtkCellIterator.h>
#include  "FEM4EllipticPDE.h"

namespace Lemma {

    /** \addtogroup FEM4EllipticPDE
     @{
     */

    /**
      \brief   Provides modelling of linear magnetic media
      \details This class solves the problem
        \f{equation}{
            \nabla^2 u(\mathbf{r}) = \nabla \cdot \kappa(\mathbf{r}) \mathbf{H}_0,
        \f}
        where \f$ \mathbf{H}_0\f$ is the static <B>homogeneous</B> inducing field, \f$ \kappa \f$
        is the <B>isotropic</B> magnetic suceptibility. The secondary field can be calculated
        \f$ \mathbf{H} = -\nabla \cdot u \f$
     */
    class LinearMag : public FEM4EllipticPDE {

        friend std::ostream &operator << (std::ostream &stream, const LinearMag &ob);

        public:

        // ====================  LIFECYCLE     =======================

        /**
         * @copybrief LemmaObject::NewSP()
         * @copydetails LemmaObject::NewSP()
         */
        static std::shared_ptr<LinearMag> NewSP();

        /** Default protected constructor, use New */
        LinearMag (const ctor_key& key);

        /** Protected DeDerializing constructor, use factory DeSerialize  method*/
        LinearMag (const YAML::Node& node, const ctor_key& key);

        /** Default protected destructor, use Delete */
        ~LinearMag ();

        /**
         *  Uses YAML to serialize this object.
         *  @return a YAML::Node
         */
        YAML::Node Serialize() const;

        /**
         *   Constructs an object from a YAML::Node.
         */
        static std::shared_ptr<LinearMag> DeSerialize(const YAML::Node& node);

        // ====================  OPERATORS     =======================

        // ====================  OPERATIONS    =======================

        // ====================  ACCESS        =======================

        /**
         *  @param[in] B0 is the incident magnetic (-induction) field
         *  @param[in] U is a MAGUNITS enum specifying the units of measurement
         */
        void SetInducingMagFieldVector( const Vector3r& B0, const MAGUNITS& U );

        /**
         *  @param[in] intensity is the incident magnetic (-induction) field intensity
         *  @param[in] inc is the incident magnetic (-induction) field inclination in degrees
         *  @param[in] dec is the incident magnetic (-induction) field declination in degrees
         *  @param[in] U is a MAGUNITS enum specifying the units of intensity
         */
        void SetInducingMagField( const Real& intensity, const Real& inclination,
                const Real& declination, const MAGUNITS& U );


        /**
         *  Calculates the right hand side of the equation
         *   \f$ \nabla \cdot \kappa \mathbf{H}_0 \f$
         */
        void CalculateRHS( const std::string& susName );

        // ====================  INQUIRY       =======================

        /** Returns the name of the underlying class, similiar to Python's type */
        virtual std::string GetName() const { return this->CName; }

        protected:

        // ====================  LIFECYCLE     =======================

        private:

        // ====================  DATA MEMBERS  =========================

        Vector3r    B0;

        /**
         *   Used internally to scale mag units into Tesla
         */
        void ScaleB0 ( const MAGUNITS& U);

        static constexpr auto CName = "LinearMag";

    }; // -----  end of class  LinearMag  -----

    /*! @} */ // End of group

}		// -----  end of Lemma  name  -----

#endif   // ----- #ifndef LINEARMAG_INC  -----