class_docstr: Cubic interpolator on a triangular grid.
  
  In one-dimension - on a segment - a cubic interpolating function is
  defined by the values of the function and its derivative at both ends.
  This is almost the same in 2D inside a triangle, except that the values
  of the function and its 2 derivatives have to be defined at each triangle
  node.
  
  The CubicTriInterpolator takes the value of the function at each node -
  provided by the user - and internally computes the value of the
  derivatives, resulting in a smooth interpolation.
  (As a special feature, the user can also impose the value of the
  derivatives at each node, but this is not supposed to be the common
  usage.)
  
  Parameters
  ----------
  triangulation : `~matplotlib.tri.Triangulation`
      The triangulation to interpolate over.
  z : (npoints,) array-like
      Array of values, defined at grid points, to interpolate between.
  kind : {'min_E', 'geom', 'user'}, optional
      Choice of the smoothing algorithm, in order to compute
      the interpolant derivatives (defaults to 'min_E'):
  
      - if 'min_E': (default) The derivatives at each node is computed
        to minimize a bending energy.
      - if 'geom': The derivatives at each node is computed as a
        weighted average of relevant triangle normals. To be used for
        speed optimization (large grids).
      - if 'user': The user provides the argument *dz*, no computation
        is hence needed.
  
  trifinder : `~matplotlib.tri.TriFinder`, optional
      If not specified, the Triangulation's default TriFinder will
      be used by calling `.Triangulation.get_trifinder`.
  dz : tuple of array-likes (dzdx, dzdy), optional
      Used only if  *kind* ='user'. In this case *dz* must be provided as
      (dzdx, dzdy) where dzdx, dzdy are arrays of the same shape as *z* and
      are the interpolant first derivatives at the *triangulation* points.
  
  Methods
  -------
  `__call__` (x, y) : Returns interpolated values at (x, y) points.
  `gradient` (x, y) : Returns interpolated derivatives at (x, y) points.
  
  Notes
  -----
  This note is a bit technical and details how the cubic interpolation is
  computed.
  
  The interpolation is based on a Clough-Tocher subdivision scheme of
  the *triangulation* mesh (to make it clearer, each triangle of the
  grid will be divided in 3 child-triangles, and on each child triangle
  the interpolated function is a cubic polynomial of the 2 coordinates).
  This technique originates from FEM (Finite Element Method) analysis;
  the element used is a reduced Hsieh-Clough-Tocher (HCT)
  element. Its shape functions are described in [1]_.
  The assembled function is guaranteed to be C1-smooth, i.e. it is
  continuous and its first derivatives are also continuous (this
  is easy to show inside the triangles but is also true when crossing the
  edges).
  
  In the default case (*kind* ='min_E'), the interpolant minimizes a
  curvature energy on the functional space generated by the HCT element
  shape functions - with imposed values but arbitrary derivatives at each
  node. The minimized functional is the integral of the so-called total
  curvature (implementation based on an algorithm from [2]_ - PCG sparse
  solver):
  
  .. math::
  
      E(z) = \frac{1}{2} \int_{\Omega} \left(
          \left( \frac{\partial^2{z}}{\partial{x}^2} \right)^2 +
          \left( \frac{\partial^2{z}}{\partial{y}^2} \right)^2 +
          2\left( \frac{\partial^2{z}}{\partial{y}\partial{x}} \right)^2
      \right) dx\,dy
  
  If the case *kind* ='geom' is chosen by the user, a simple geometric
  approximation is used (weighted average of the triangle normal
  vectors), which could improve speed on very large grids.
  
  References
  ----------
  .. [1] Michel Bernadou, Kamal Hassan, "Basis functions for general
      Hsieh-Clough-Tocher triangles, complete or reduced.",
      International Journal for Numerical Methods in Engineering,
      17(5):784 - 789. 2.01.
  .. [2] C.T. Kelley, "Iterative Methods for Optimization".
class_docstr_tok: ["Cubic","interpolator","on","a","triangular","grid",".","In","one-dimension","-","on","a","segment","-","a","cubic","interpolating","function","is","defined","by","the","values","of","the","function","and","its","derivative","at","both","ends",".","This","is","almost","the","same","in","2D","inside","a","triangle",",","except","that","the","values","of","the","function","and","its","2","derivatives","have","to","be","defined","at","each","triangle","node",".","The","CubicTriInterpolator","takes","the","value","of","the","function","at","each","node","-","provided","by","the","user","-","and","internally","computes","the","value","of","the","derivatives",",","resulting","in","a","smooth","interpolation",".","(","As","a","special","feature",",","the","user","can","also","impose","the","value","of","the","derivatives","at","each","node",",","but","this","is","not","supposed","to","be","the","common","usage",".",")","Parameters","--","--","--","--","--","triangulation",":","`","~matplotlib.tri.Triangulation","`","The","triangulation","to","interpolate","over",".","z",":","(","npoints",",",")","array-like","Array","of","values",",","defined","at","grid","points",",","to","interpolate","between",".","kind",":","{","'min_E","'",",","'geom","'",",","'user","'","}",",","optional","Choice","of","the","smoothing","algorithm",",","in","order","to","compute","the","interpolant","derivatives","(","defaults","to","'min_E","'",")",":","-","if","'min_E","'",":","(","default",")","The","derivatives","at","each","node","is","computed","to","minimize","a","bending","energy",".","-","if","'geom","'",":","The","derivatives","at","each","node","is","computed","as","a","weighted","average","of","relevant","triangle","normals",".","To","be","used","for","speed","optimization","(","large","grids",")",".","-","if","'user","'",":","The","user","provides","the","argument","*","dz","*",",","no","computation","is","hence","needed",".","trifinder",":","`","~matplotlib.tri.TriFinder","`",",","optional","If","not","specified",",","the","Triangulation","'s","default","TriFinder","will","be","used","by","calling","`",".Triangulation.get_trifinder","`",".","dz",":","tuple","of","array-likes","(","dzdx",",","dzdy",")",",","optional","Used","only","if","*","kind","*","='user","'",".","In","this","case","*","dz","*","must","be","provided","as","(","dzdx",",","dzdy",")","where","dzdx",",","dzdy","are","arrays","of","the","same","shape","as","*","z","*","and","are","the","interpolant","first","derivatives","at","the","*","triangulation","*","points",".","Methods","--","--","--","-","`","__call__","`","(","x",",","y",")",":","Returns","interpolated","values","at","(","x",",","y",")","points",".","`","gradient","`","(","x",",","y",")",":","Returns","interpolated","derivatives","at","(","x",",","y",")","points",".","Notes","--","--","-","This","note","is","a","bit","technical","and","details","how","the","cubic","interpolation","is","computed",".","The","interpolation","is","based","on","a","Clough-Tocher","subdivision","scheme","of","the","*","triangulation","*","mesh","(","to","make","it","clearer",",","each","triangle","of","the","grid","will","be","divided","in","3","child-triangles",",","and","on","each","child","triangle","the","interpolated","function","is","a","cubic","polynomial","of","the","2","coordinates",")",".","This","technique","originates","from","FEM","(","Finite","Element","Method",")","analysis",";","the","element","used","is","a","reduced","Hsieh-Clough-Tocher","(","HCT",")","element",".","Its","shape","functions","are","described","in","[","1","]","_",".","The","assembled","function","is","guaranteed","to","be","C1-smooth",",","i.e",".","it","is","continuous","and","its","first","derivatives","are","also","continuous","(","this","is","easy","to","show","inside","the","triangles","but","is","also","true","when","crossing","the","edges",")",".","In","the","default","case","(","*","kind","*","='min_E","'",")",",","the","interpolant","minimizes","a","curvature","energy","on","the","functional","space","generated","by","the","HCT","element","shape","functions","-","with","imposed","values","but","arbitrary","derivatives","at","each","node",".","The","minimized","functional","is","the","integral","of","the","so-called","total","curvature","(","implementation","based","on","an","algorithm","from","[","2","]","_","-","PCG","sparse","solver",")",":","..","math",":",":","E","(","z",")","=","\\frac","{","1","}","{","2","}","\\int_","{","\\Omega","}","\\left","(","\\left","(","\\frac","{","\\partial^2","{","z","}","}","{","\\partial","{","x","}","^2","}","\\right",")","^2","+","\\left","(","\\frac","{","\\partial^2","{","z","}","}","{","\\partial","{","y","}","^2","}","\\right",")","^2","+","2\\left","(","\\frac","{","\\partial^2","{","z","}","}","{","\\partial","{","y","}","\\partial","{","x","}","}","\\right",")","^2","\\right",")","dx\\",",","dy","If","the","case","*","kind","*","='geom","'","is","chosen","by","the","user",",","a","simple","geometric","approximation","is","used","(","weighted","average","of","the","triangle","normal","vectors",")",",","which","could","improve","speed","on","very","large","grids",".","References","--","--","--","--","--","..","[","1","]","Michel","Bernadou",",","Kamal","Hassan",",","``","Basis","functions","for","general","Hsieh-Clough-Tocher","triangles",",","complete","or","reduced",".","``",",","International","Journal","for","Numerical","Methods","in","Engineering",",","17","(","5",")",":784","-","789",".","2.01",".","..","[","2","]","C.T",".","Kelley",",","``","Iterative","Methods","for","Optimization","''","."]
code: def __init__(
      self, triangulation, z, kind="min_E", trifinder=None, dz=None
  ):
      super().__init__(triangulation, z, trifinder)
  
      # Loads the underlying c++ _triangulation.
      # (During loading, reordering of triangulation._triangles may occur so
      # that all final triangles are now anti-clockwise)
      self._triangulation.get_cpp_triangulation()
  
      # To build the stiffness matrix and avoid zero-energy spurious modes
      # we will only store internally the valid (unmasked) triangles and
      # the necessary (used) points coordinates.
      # 2 renumbering tables need to be computed and stored:
      #  - a triangle renum table in order to translate the result from a
      #    TriFinder instance into the internal stored triangle number.
      #  - a node renum table to overwrite the self._z values into the new
      #    (used) node numbering.
      tri_analyzer = TriAnalyzer(self._triangulation)
      (
          compressed_triangles,
          compressed_x,
          compressed_y,
          tri_renum,
          node_renum,
      ) = tri_analyzer._get_compressed_triangulation()
      self._triangles = compressed_triangles
      self._tri_renum = tri_renum
      # Taking into account the node renumbering in self._z:
      valid_node = node_renum != -1
      self._z[node_renum[valid_node]] = self._z[valid_node]
  
      # Computing scale factors
      self._unit_x = np.ptp(compressed_x)
      self._unit_y = np.ptp(compressed_y)
      self._pts = np.column_stack(
          [compressed_x / self._unit_x, compressed_y / self._unit_y]
      )
      # Computing triangle points
      self._tris_pts = self._pts[self._triangles]
      # Computing eccentricities
      self._eccs = self._compute_tri_eccentricities(self._tris_pts)
      # Computing dof estimations for HCT triangle shape function
      _api.check_in_list(["user", "geom", "min_E"], kind=kind)
      self._dof = self._compute_dof(kind, dz=dz)
      # Loading HCT element
      self._ReferenceElement = _ReducedHCT_Element()
  
imports: import numpy
  from matplotlib import _api
  from matplotlib.tri import Triangulation
  from matplotlib.tri._trifinder import TriFinder
  from matplotlib.tri._tritools import TriAnalyzer
label_desc: Use image node_id 1 to create a new CubicTriInterpolator object from inherited base classes: TriInterpolator with example: obj = CubicTriInterpolator(triangulation, z, kind, trifinder, dz)