<?xml version="1.0" encoding="UTF-8"?>
<refentry version="5.0-subset Scilab" xml:id="gf_mesh_set" xml:lang="en"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:html="http://www.w3.org/1999/xhtml"
          xmlns:db="http://docbook.org/ns/docbook">
  <refnamediv>
    <refname>gf_mesh_set</refname>
    <refpurpose>  General function for modification of a mesh object.
</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>Calling Sequence</title>

    <synopsis>PIDs = gf_mesh_set(mesh M, 'pts', mat PTS)</synopsis>
    <synopsis>PIDs = gf_mesh_set(mesh M, 'add point', mat PTS)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'del point', ivec PIDs)</synopsis>
    <synopsis>CVIDs = gf_mesh_set(mesh M, 'add convex', geotrans GT, mat PTS)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'del convex', mat CVIDs)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'del convex of dim', ivec DIMs)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'translate', vec V)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'transform', mat T)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'boundary', int rnum, mat CVFIDs)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'region', int rnum, mat CVFIDs)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'region intersect', int r1, int r2)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'region merge', int r1, int r2)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'region substract', int r1, int r2)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'delete boundary', int rnum, mat CVFIDs)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'delete region', ivec RIDs)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'merge', mesh m2)</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'optimize structure')</synopsis>
    <synopsis>gf_mesh_set(mesh M, 'refine'[, ivec CVIDs])</synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Description</title>
    <para>  General function for modification of a mesh object.
</para>
  </refsection>

  <refsection>
    <title>Command list</title>

    <itemizedlist>
    <listitem>
    <para><literal>PIDs = gf_mesh_set(mesh M, 'pts', mat PTS)</literal></para>

    <para>       Replace the coordinates of the mesh points with those given in <literal>PTS</literal>.
    </para>
    </listitem>

    <listitem>
    <para><literal>PIDs = gf_mesh_set(mesh M, 'add point', mat PTS)</literal></para>

    <para>       Insert new points in the mesh and return their #ids.

    <literal>PTS</literal> should be an <literal></literal>nxm<literal></literal> matrix , where <literal></literal>n<literal></literal> is the mesh
    dimension, and <literal></literal>m<literal></literal> is the number of points that will be
    added to the mesh. On output, <literal>PIDs</literal> contains the point #ids
    of these new points.

    Remark: if some points are already part of the mesh (with a small
    tolerance of approximately <literal></literal>1e-8<literal></literal>), they won't be inserted again,
    and <literal>PIDs</literal> will contain the previously assigned #ids of these
    points.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'del point', ivec PIDs)</literal></para>

    <para>       Removes one or more points from the mesh.

    <literal>PIDs</literal> should contain the point #ids, such as the one returned by
    the 'add point' command.
    </para>
    </listitem>

    <listitem>
    <para><literal>CVIDs = gf_mesh_set(mesh M, 'add convex', geotrans GT, mat PTS)</literal></para>

    <para>       Add a new convex into the mesh.

    The convex structure (triangle, prism,...) is given by <literal>GT</literal>
    (obtained with gf_geotrans('...')), and its points are given by
    the columns of <literal>PTS</literal>. On return, <literal>CVIDs</literal> contains the convex #ids.
    <literal>PTS</literal> might be a 3-dimensional array in order to insert more than
    one convex (or a two dimensional array correctly shaped according
    to Fortran ordering).
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'del convex', mat CVIDs)</literal></para>

    <para>       Remove one or more convexes from the mesh.

    <literal>CVIDs</literal> should contain the convexes #ids, such as the ones
    returned by the 'add convex' command.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'del convex of dim', ivec DIMs)</literal></para>

    <para>       Remove all convexes of dimension listed in <literal>DIMs</literal>.

    For example; <literal></literal>gf_mesh_set(mesh M, 'del convex of dim', [1,2])<literal></literal> remove
    all line segments, triangles and quadrangles.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'translate', vec V)</literal></para>

    <para>         Translates each point of the mesh from <literal>V</literal>.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'transform', mat T)</literal></para>

    <para>       Applies the matrix <literal>T</literal> to each point of the mesh.

    Note that <literal>T</literal> is not required to be a <literal></literal>NxN<literal></literal> matrix (with
    <literal></literal>N = gf_mesh_get(mesh M, 'dim')<literal></literal>). Hence it is possible to transform
    a 2D mesh into a 3D one (and reciprocally).
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'boundary', int rnum, mat CVFIDs)</literal></para>

    <para>       DEPRECATED FUNCTION. Use 'region' instead.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'region', int rnum, mat CVFIDs)</literal></para>

    <para>       Assigns the region number <literal>rnum</literal> to the convex faces (or convexes)
    stored in each column of the matrix <literal>CVFIDs</literal>.

    The first row of <literal>CVFIDs</literal> contains a convex #ids, and the second row
    contains a face number in the convex (or 0
    for the whole convex (regions are usually used to store a list of
    convex faces, but you may also use them to store a list of convexes).

    If a vector is provided (or a one row matrix) the region will represent
    the corresponding set of convex.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'region intersect', int r1, int r2)</literal></para>

    <para>       Replace the region number <literal>r1</literal> with its intersection with region number <literal>r2</literal>.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'region merge', int r1, int r2)</literal></para>

    <para>       Merge region number <literal>r2</literal> into region number <literal>r1</literal>.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'region substract', int r1, int r2)</literal></para>

    <para>       Replace the region number <literal>r1</literal> with its difference with region
    number <literal>r2</literal>.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'delete boundary', int rnum, mat CVFIDs)</literal></para>

    <para>       DEPRECATED FUNCTION. Use 'delete region' instead.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'delete region', ivec RIDs)</literal></para>

    <para>         Remove the regions whose #ids are listed in <literal>RIDs</literal>
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'merge', mesh m2)</literal></para>

    <para>         Merge with the mesh <literal>m2</literal>.
      
      Overlapping points won't be duplicated. If <literal>m2</literal> is a mesh_fem object,
      its linked mesh will be used.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'optimize structure')</literal></para>

    <para>       Reset point and convex numbering.

    After optimisation, the points (resp. convexes) will
    be consecutively numbered from 1 to gf_mesh_get(mesh M, 'max pid')
    (resp. gf_mesh_get(mesh M, 'max cvid')).
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_set(mesh M, 'refine'[, ivec CVIDs])</literal></para>

    <para>       Use a Bank strategy for mesh refinement.

    If <literal>CVIDs</literal> is not given, the whole mesh is refined. Note
    that the regions, and the finite element methods and
    integration methods of the mesh_fem and mesh_im objects linked
    to this mesh will be automagically refined.
    </para>
    </listitem>

    </itemizedlist>
  </refsection>

  <refsection>
    <title>See Also</title>
    <simplelist type="inline">
      <member><link linkend="getfem_types">getfem types</link></member>
    </simplelist>
  </refsection>

  <refsection>
    <title>Authors</title>
    <para>Y. Collette</para>
  </refsection>

</refentry>
