pyHarm.Reductors.LocalHarmonicReductor
======================================

.. py:module:: pyHarm.Reductors.LocalHarmonicReductor


Classes
-------

.. autoapisummary::

   pyHarm.Reductors.LocalHarmonicReductor.LocalHarmonicReductor


Module Contents
---------------

.. py:class:: LocalHarmonicReductor(data: dict, expl_dofs: pandas.DataFrame, *args)

   Bases: :py:obj:`pyHarm.Reductors.FactoryReductors.GlobalHarmonicReductor`


   The local harmonic reductor is a reductor (inheriting from the global Harmonic reductor) aiming at reducing the number of harmonics considered in the problem while solving.

   Hence in linear situation, it is expected that the problem is gonna be reduced solely to the harmonics being involved in the forcing.
   The reduction method is based on Gastaldi et al. proposal in :
       - A method to solve the efficiency-accuracy trade-off of multi-harmonic balance calculation of structures with friction contacts.
   This Reductor is local in the sense that it keeps only the higher harmonic numbers for the needed dofs

   Attributes :
       factory_keyword (str): name to use as input when willing to create an instance of this object.
       default (dict): dictionary of default reducer options.
       max_nh (int): maximum number of harmonics.
       data (dict): dictionary of input + missing parameters from default dictionary.
       tot_dofs (int): total number of dofs.
       disp_cut_off (float): displacement cut off parameter used to put compute the criterion
       err_admissible (float): admissible error commited on the representation of the input displacement using limited amount of harmonics
       h_always_kept (np.ndarray): harmonic numbers that shall be kept in any condition
       verbose (bool): parameter to display info at each update of the number of harmonics
       tol_update (float): tolerance over the jacobian that tells if an update of the number of harmonics might be necessary


   .. py:attribute:: factory_keyword
      :type:  str
      :value: 'localHarmonic'


      keyword that is used to call the creation of this class in the factory.

      :type: str


   .. py:method:: __post_init__(*args)

      A post init method to be customized if needed when building new class.



   .. py:method:: update_reductor(xpred, J_f, expl_dofs, *args)

      Updates the number of harmonics to be solved.

      The update is made according to Gastaldi et al. paper named :
      - A method to solve the efficiency-accuracy trade-off of multi-harmonic balance calculation of structures with friction contacts (2017)
      A tolerance on the change of the Jacobian has been added in order to avoid costly update if the Jacobian remains identical to previous update.

      :param xpred: point predicted as the new starting point for the next iteration of the analysis process.
      :type xpred: np.ndarray
      :param J_f: full jacobian with respect to displacement and angular frequency (contains the correction equation residual).
      :type J_f: np.ndarray

      .. attribute:: phi

         Updated transformation matrix generated depending on the number of harmonics to keep.

         :type: np.ndarray

      :returns: same displacement vector given in input after passing through the reductor
                np.ndarray: same jacobian matrix given in input after passing through the reductor
                pd.DataFrame: same explicit dof DataFrame after passing through the reductor
      :rtype: np.ndarray



   .. py:method:: build_phi(nh_kept, local=False)

      Creates the masking phi matrix based on the harmonic numbers that are to be kept.

      :param nh_kept: Harmonic numbers to keep in the reduced vector.
      :type nh_kept: np.ndarray

      .. attribute:: phi

         Updated transformation matrix.

         :type: np.nd.array



   .. py:method:: _harmonic_selection(criterion)

      "
      Based on the criterion values and the harmonics that are set to be kept all the time,
      creates the array with all the harmonics to keep in the calculation for each dof.

      :param criterion: array of booleans that indicates if the criterion is verified.
      :type criterion: np.ndarray[bool]

      :returns: array of harmonic numbers to keep.
      :rtype: np.ndarray



   .. py:method:: _get_output_expl_dofs()

      Obtains the modified explicit dof DataFrame after passing through the reducer.

      :returns: Modified explicit dof DataFrame after passing through the reducer.
      :rtype: np.ndarray