<?xml version="1.0" encoding="UTF-8"?>
<refentry version="5.0-subset Scilab" xml:id="gf_model_get" 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_model_get</refname>
    <refpurpose>  Get information from a model object.
</refpurpose>
  </refnamediv>

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

    <synopsis>b = gf_model_get(model M, 'is_complex')</synopsis>
    <synopsis>T = gf_model_get(model M, 'nbdof')</synopsis>
    <synopsis>T = gf_model_get(model M, 'tangent_matrix')</synopsis>
    <synopsis>gf_model_get(model M, 'rhs')</synopsis>
    <synopsis>gf_model_get(model M, 'brick term rhs', int ind_brick[, int ind_term, int sym, int ind_iter])</synopsis>
    <synopsis>z = gf_model_get(model M, 'memsize')</synopsis>
    <synopsis>gf_model_get(model M, 'listvar')</synopsis>
    <synopsis>gf_model_get(model M, 'listbricks')</synopsis>
    <synopsis>V = gf_model_get(model M, 'variable', string name[, int niter])</synopsis>
    <synopsis>V = gf_model_get(model M, 'mesh fem of variable', string name)</synopsis>
    <synopsis>name = gf_model_get(model M, 'mult varname Dirichlet', int ind_brick)</synopsis>
    <synopsis>I = gf_model_get(model M, 'interval of variable', string varname)</synopsis>
    <synopsis>V = gf_model_get(model M, 'from variables')</synopsis>
    <synopsis>gf_model_get(model M, 'assembly'[, string option])</synopsis>
    <synopsis>{nbit, converged} = gf_model_get(model M, 'solve'[, ...])</synopsis>
    <synopsis>gf_model_get(model M, 'test tangent matrix'[, scalar EPS[, int NB[, scalar scale]]])</synopsis>
    <synopsis>V = gf_model_get(model M, 'compute isotropic linearized Von Mises or Tresca', string varname, string dataname_lambda, string dataname_mu, mesh_fem mf_vm[, string version])</synopsis>
    <synopsis>V = gf_model_get(model M, 'compute Von Mises or Tresca', string varname, string lawname, string dataname, mesh_fem mf_vm[, string version])</synopsis>
    <synopsis>V = gf_model_get(model M, 'compute second Piola Kirchhoff tensor', string varname, string lawname, string dataname, mesh_fem mf_sigma)</synopsis>
    <synopsis>V = gf_model_get(model M, 'compute plasticity Von Mises or Tresca', string datasigma, mesh_fem mf_vm[, string version])</synopsis>
    <synopsis>gf_model_get(model M, 'compute plasticity constraints', mesh_im mim, string varname, string projname, string datalambda, string datamu, string datathreshold, string datasigma)</synopsis>
    <synopsis>V = gf_model_get(model M, 'compute plastic part', mesh_im mim, mesh_fem mf_pl, string varname, string projname, string datalambda, string datamu, string datathreshold, string datasigma)</synopsis>
    <synopsis>M = gf_model_get(model M, 'matrix term', int ind_brick, int ind_term)</synopsis>
    <synopsis>s = gf_model_get(model M, 'char')</synopsis>
    <synopsis>gf_model_get(model M, 'display')</synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Description</title>
    <para>  Get information from a model object.
</para>
  </refsection>

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

    <itemizedlist>
    <listitem>
    <para><literal>b = gf_model_get(model M, 'is_complex')</literal></para>

    <para>         Return 0 is the model is real, 1 if it is complex.
    </para>
    </listitem>

    <listitem>
    <para><literal>T = gf_model_get(model M, 'nbdof')</literal></para>

    <para>         Return the total number of degrees of freedom of the model.
    </para>
    </listitem>

    <listitem>
    <para><literal>T = gf_model_get(model M, 'tangent_matrix')</literal></para>

    <para>         Return the tangent matrix stored in the model .
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_model_get(model M, 'rhs')</literal></para>

    <para>         Return the right hand side of the tangent problem.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_model_get(model M, 'brick term rhs', int ind_brick[, int ind_term, int sym, int ind_iter])</literal></para>

    <para>         Gives the access to the part of the right hand side of a term
      of a particular nonlinear brick. Does not account of the eventual
      time dispatcher. An assembly of the rhs has to be done first.
      <literal>ind_brick</literal> is the brick index. <literal>ind_term</literal> is the index of the
      term inside the brick (default value : 1).
      <literal>sym</literal> is to access to the second right hand side of for symmetric
      terms acting on two different variables (default is 0).
      <literal>ind_iter</literal> is the iteration number when time dispatchers are
      used (default is 1).
      
    </para>
    </listitem>

    <listitem>
    <para><literal>z = gf_model_get(model M, 'memsize')</literal></para>

    <para>         Return a rough approximation of the amount of memory (in bytes) used by
      the model.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_model_get(model M, 'listvar')</literal></para>

    <para>         print to the output the list of variables and constants of the model.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_model_get(model M, 'listbricks')</literal></para>

    <para>         print to the output the list of bricks of the model.
    </para>
    </listitem>

    <listitem>
    <para><literal>V = gf_model_get(model M, 'variable', string name[, int niter])</literal></para>

    <para>         Gives the value of a variable or data.
    </para>
    </listitem>

    <listitem>
    <para><literal>V = gf_model_get(model M, 'mesh fem of variable', string name)</literal></para>

    <para>         Gives access to the <literal>mesh_fem</literal> of a variable or data.
    </para>
    </listitem>

    <listitem>
    <para><literal>name = gf_model_get(model M, 'mult varname Dirichlet', int ind_brick)</literal></para>

    <para>         Gives the name of the multiplier variable for a Dirichlet brick.
      If the brick is not a Dirichlet condition with multiplier brick,
      this function has an undefined behavior
    </para>
    </listitem>

    <listitem>
    <para><literal>I = gf_model_get(model M, 'interval of variable', string varname)</literal></para>

    <para>         Gives the interval of the variable <literal>varname</literal> in the linear system of
      the model.
    </para>
    </listitem>

    <listitem>
    <para><literal>V = gf_model_get(model M, 'from variables')</literal></para>

    <para>         Return the vector of all the degrees of freedom of the model consisting
      of the concatenation of the variables of the model (useful
      to solve your problem with you own solver). 
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_model_get(model M, 'assembly'[, string option])</literal></para>

    <para>         Assembly of the tangent system taking into account the terms
      from all bricks. <literal>option</literal>, if specified, should be 'build_all',
      'build_rhs', 'build_matrix' or 'pseudo_potential' (in that case,
      the pseudo_potential is returned).
      The default is to build the whole
      tangent linear system (matrix and rhs). This function is useful
      to solve your problem with you own solver. 
    </para>
    </listitem>

    <listitem>
    <para><literal>{nbit, converged} = gf_model_get(model M, 'solve'[, ...])</literal></para>

    <para>       Run the standard getfem solver.

    Note that you should be able to use your own solver if you want
    (it is possible to obtain the tangent matrix and its right hand
    side with the gf_model_get(model M, 'tangent matrix') etc.).

    Various options can be specified:

    - 'noisy' or 'very_noisy'
       the solver will display some information showing the progress
       (residual values etc.).
    - 'max_iter', int NIT
       set the maximum iterations numbers.
    - 'max_res', @float RES
       set the target residual value.
    - 'diverged_res', @float RES
       set the threshold value of the residual beyond which the iterative
       method is considered to diverge (default is 1e200).
    - 'lsolver', string SOLVER_NAME
       select explicitely the solver used for the linear systems (the
       default value is 'auto', which lets getfem choose itself).
       Possible values are 'superlu', 'mumps' (if supported),
       'cg/ildlt', 'gmres/ilu' and 'gmres/ilut'.
    - 'lsearch', string LINE_SEARCH_NAME
       select explicitely the line search method used for the linear systems (the
       default value is 'default').
       Possible values are 'simplest', 'systematic', 'quadratic' or 'basic'.
    - 'with pseudo potential'
      for nonlinear problems, the criterion of the line search will
      be a pseudo potential instead of the residual. Still experimental since
      not all bricks define a pseudo potential.

      Return the number of iterations, if a iterative method is used.
      
      Note that it is possible to disable some variables
      (see gf_model_set(model M, 'disable variable') ) in order to
      solve the problem only with respect to a subset of variables (the
      disabled variables are the considered as data) for instance to
      replace the global Newton strategy with a fixed point one.

      
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_model_get(model M, 'test tangent matrix'[, scalar EPS[, int NB[, scalar scale]]])</literal></para>

    <para>         Test the consistency of the tangent matrix in some random positions
      and random directions (useful to test newly created bricks).
      <literal>EPS</literal> is the value of the small parameter for the finite difference
      computation of the derivative is the random direction (default is 1E-6).
      <literal>NN</literal> is the number of tests (default is 100). <literal>scale</literal> is a parameter
      for the random position (default is 1). Each dof od the random
      position is chosen in the range [-scale, scale].
      
    </para>
    </listitem>

    <listitem>
    <para><literal>V = gf_model_get(model M, 'compute isotropic linearized Von Mises or Tresca', string varname, string dataname_lambda, string dataname_mu, mesh_fem mf_vm[, string version])</literal></para>

    <para>         Compute the Von-Mises stress or the Tresca stress of a field (only
      valid for isotropic linearized elasticity in 3D). <literal>version</literal> should
      be  'Von_Mises' or 'Tresca' ('Von_Mises' is the default). 
    </para>
    </listitem>

    <listitem>
    <para><literal>V = gf_model_get(model M, 'compute Von Mises or Tresca', string varname, string lawname, string dataname, mesh_fem mf_vm[, string version])</literal></para>

    <para>         Compute on <literal>mf_vm</literal> the Von-Mises stress or the Tresca stress of a field
      for nonlinear elasticity in 3D. <literal>lawname</literal> is the constitutive law which
      could be 'SaintVenant Kirchhoff', 'Mooney Rivlin' or 'Ciarlet Geymonat'.
      <literal>dataname</literal> is a vector of parameters for the constitutive law. Its length
      depends on the law. It could be a short vector of constant values or a
      vector field described on a finite element method for variable coefficients.
      <literal>version</literal> should be  'Von_Mises' or 'Tresca' ('Von_Mises' is the default). 
    </para>
    </listitem>

    <listitem>
    <para><literal>V = gf_model_get(model M, 'compute second Piola Kirchhoff tensor', string varname, string lawname, string dataname, mesh_fem mf_sigma)</literal></para>

    <para>         Compute on <literal>mf_sigma</literal> the second Piola Kirchhoff stress tensor of a field
      for nonlinear elasticity in 3D. <literal>lawname</literal> is the constitutive law which
      could be 'SaintVenant Kirchhoff', 'Mooney Rivlin' or 'Ciarlet Geymonat'.
      <literal>dataname</literal> is a vector of parameters for the constitutive law. Its length
      depends on the law. It could be a short vector of constant values or a
      vector field described on a finite element method for variable
      coefficients.
     
    </para>
    </listitem>

    <listitem>
    <para><literal>V = gf_model_get(model M, 'compute plasticity Von Mises or Tresca', string datasigma, mesh_fem mf_vm[, string version])</literal></para>

    <para>         Compute on <literal>mf_vm</literal> the Von-Mises or the Tresca stress of a field for plasticity and return it into the vector V.
      <literal>datasigma</literal> is a vector which contains the stress constraints values supported by the mesh.
      <literal>version</literal> should be  'Von_Mises' or 'Tresca' ('Von_Mises' is the default).
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_model_get(model M, 'compute plasticity constraints', mesh_im mim, string varname, string projname, string datalambda, string datamu, string datathreshold, string datasigma)</literal></para>

    <para>         Compute and save the stress constraints sigma for other hypothetical iterations.
      'mim' is the integration method to use for the computation.
      'varname' is the main variable of the problem.
      'projname' is the type of projection to use. For the moment it could only be 'Von Mises' or 'VM'.
      'datalambda' and 'datamu' are the Lame coefficients of the material.
      'datasigma' is a vector which will contains the new stress constraints values.
    </para>
    </listitem>

    <listitem>
    <para><literal>V = gf_model_get(model M, 'compute plastic part', mesh_im mim, mesh_fem mf_pl, string varname, string projname, string datalambda, string datamu, string datathreshold, string datasigma)</literal></para>

    <para>         Compute on <literal>mf_pl</literal> the plastic part and return it into the vector V.
      <literal>datasigma</literal> is a vector which contains the stress constraints values supported by the mesh.
    </para>
    </listitem>

    <listitem>
    <para><literal>M = gf_model_get(model M, 'matrix term', int ind_brick, int ind_term)</literal></para>

    <para>         Gives the matrix term ind_term of the brick ind_brick if it exists
      
    </para>
    </listitem>

    <listitem>
    <para><literal>s = gf_model_get(model M, 'char')</literal></para>

    <para>         Output a (unique) string representation of the model.

      This can be used to perform comparisons between two
      different model objects.
      This function is to be completed.
      
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_model_get(model M, 'display')</literal></para>

    <para>         displays a short summary for a model object.
    </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>
