rita commands

Running rita creates a command line environment that enables defining problems to solve and data for these problems.
Here is a list of available commands in the rita console application. These commands can be classified in categories:

• Setting commands: They can be invoked for specific utility to set up some global properties.
• Data commands: Commands that define data entities, modify or explore them.
• Solver commands: Commands to define problems to solve and solve them.
• Calculator: Commands to perform some simple calculus.

• Documentation Guide

  In the present documentation, rita commands are presented according to the following rules:
  command arg1|arg2=<v> [arg3|arg4=<v1>,<v2>]
  This means that the arguments arg1 and arg2 are mandatory but exclusive. Argument arg1 needs a value v. The arguments arg3 and arg4 are optional but exclusive. In addition, arg4 needs two values: v1 and v2.
  Examples of possible combinations:

  • command arg1
  • command arg2=v2 arg3
  • command arg1=v1 arg4=x,y

• Syntax Rules

  • Running rita consists in typing commands that may need specific arguments
  • Some commands have a submenu to specify more data. In addition some commands can be invoked either in short or extended versions.
  • For a friendly use of rita, this one can use an input script file. The name of this file can be given as an argument of the command rita.
  • A line starting with the character # is a comment line that is ignored by the application.
  • A line starting with the character ! defines a system shell command.
  • The command exit (or quit) causes quitting the application, while pressing the Ctrl-D sequence interrupts the execution.
  • In the case where the user is in a submenu, the command end or < enables going to command level.
  • Some commands have a short version to simplify their usage in interactive mode. This one is shown in parenthesis in the present guide.

• Setting Commands

  Here is the list of setting commands:

  • help (or ?): displays the list of available commands with a brief description.
  • load <file>
    Read commands in a given script file.
  • license (or lic): displays the License agreement of the application.
  • set <argument> <value>
    Enables modifying default configuration parameters.
    • The argument verbosity (or verb) sets a value for verbosity parameter. Its default value is 1. The value can be chosen between 0 and 10, from a silent execution to extensive messaging.
    • history enables choosing a history file name rather than default name (.rita.his). The value is the file name. The history file echoes all typed commands in rita. It can be used, after possibly changing its name for a new execution.
    • log enables choosing a log file name rather than default name (.rita.log). The value is the file name. The log file contains all found errors while running rita.

• Data commands

  • Command vector enables defining a vector. A vector in rita can be used as datum for a system of equations, a solution of a PDE defined at nodes, etc.
    A vector can be defined by one of the three methods:

    • By calculator. For instance, the command
      v = {1.0,-1.2,2.3}
      defines a row vector with dimension 3, with given components.
    • From a solver. For instance when defining a partial differential equation, declaring a variable name defines it as a vector in rita and size it.
    • By using the present command which defined a column vector.

    Synopsis:
    vector [name=<nm>] [size=<n> | grid=<g> | mesh=<m>] [file=<f>] 
    We note that all arguments are optional but at least one argument is mandatory.

    nm	Name of (column) vector. This argument is optional.
    n	Size of vector when this one is defined by its size.
    g	A vector can be associated to a grid. In this case, its size is the total number Size of vector when this one is defined by its size. For this purpose, g is the grid name, assumed to be defined already.
    m	A vector can be associated to a mesh. In this case m is the mesh name, assumed to be defined already.
    f	Name of a file from which vector contents are read. The vector must have the ofeli format.

  • Command matrix enables defining a matrix.
    A matrix can be defined by one of the three methods:

    • By calculator. For instance, the command
      M = matrix(2,3)
      defines a 2x3-matrix initialized by 0. Once declared, an entry of the matrix can be given for instance by
      M[0,2]=5
      Note that the first row, first column entry is M[0,0], and generally the n-th row, m -th column entry is M[n-1,m-1].
    • By using the present command.

    Synopsis:
    matrix [name=<nm>] [file=<f>] [nr=<n1>] [nc=<n2>]
    We note that all arguments are optional but at least one argument is mandatory.

    nm	Name of matrix. This argument is optional.
    f	Name of a file containing the matrix. This file must and XML file as defined in ofeli.
    n1	Number of rows of matrix.
    n2	Number of columns of matrix. If only the number of rows is given, the matrix is a square one.

  • Command tabulation enables reading a tabulated function from a file.
    Synopsis:
    tabulation <f>
    where f is the file name, in ofeli format.
  • Command mesh builds a finite element mesh.
    A finite element mesh is the discretization of the physical domain where the process to study takes place. This means partitioning the domain (1-D, 2-D or 3-D) into specific subdomains. More commonly, intervals in 1-D, triangles or quadrilaterals in 2-D, and tetrahedra, hexahedra or pentahedra in 3-D.
    rita does not contain a powerful mesh generator. We use a simple 2-D generator issued from the ofeli library. For unstructuerd 2-D and 3-D meshes rita uses the open source mesh generator Gmsh. For this, it is highly recommended to install rita and Gmsh. The purpose of command mesh is to prepare data for Gmsh and generate the mesh. Once the command mesh is entered, the following subcommands are available:
    help or ?, 1d, rectangle, cube, point, curve, surface, volume, contour, code, generate, nbdof, list, plot, clear, save, read

    • Keyword 1d constructs a 1-D mesh of an interval:
      1d [domain=<m>,<M>] [ne=<n>] [codes=<c1>,<c2>]  [nbdof=<d>]

      m, M	Extremal coordinates of interval ends. The default values are 0., 1.
      n	Number of elements in the interval. Its default value is 10.
      c1, c2	Codes associated to the first and the last node. These integer values are necessary to enforce boundary conditions. A code 0 (Default value) means no condition to prescribe.
      d	Number of degrees of freedom associated to any generated node. Default value is 1.

    • Keyword rectangle constructs a 2-D mesh of a rectangle:
      rectangle [min=<mx>,<my>] [max=<Mx>,<My>] [ne=<nx>,<ny>]  [codes=<c1><c2><c3><c4>] [nbdof=<d>]

      mx, my	Coordinates of the lower left corner of the rectangle. The default values are 0., 0.
      Mx, My	Coordinates of the upper right corner of the rectangle. The default values are 1., 1.
      nx, ny	is the number of elements in x and y direction respectively. Their default value is 10.
      c1, c2, c3, c4	Codes associated to the nodes generated on the lines y=my, x=Mx, y=My, x=mx respectively. These integer values are necessary to enforce boundary conditions. A code 0 (Default value) means no condition to prescribe.
      d	Number of degrees of freedom associated to any generated node. Default value is 1.

    • Keyword cube constructs a 3-D mesh of a cube-like domain:
      cube [min=<mx><my><mz>] [max=<Mx><My><Mz>]  [ne=<nx><ny><nz>]
          [codes=<cxm>,<cxM>,<cym>,<cyM>,<czm>,<czM>] [nbdof=<d>]

      mx, my, mz	Minimal coordinates in each direction. The default values are 0., 0., 0.
      Mx, My, Mz	Maximal coordinates in each direction. The default values are 1., 1., 1.
      nx, ny, nz	Number of elements in x, y and z direction respectively. Their default values are 10.
      cxm, cxM, cym, cyM, czm, czM	Codes associated to the nodes generated on the face x=mx, x=Mx, y=my, y=My, z=mz, z=Mz respectively. These integer values are necessary to enforce boundary conditions. A code 0 (Default value) means no condition to prescribe.
      d	Number of degrees of freedom associated to any generated node. Default value is 1

    • Keyword point defines a point (vertex) in a polygonal or polyhedral domain:
      point label=<n> coord=<x>[,<y>,<z>] size=<h>

      n	Point's label.
      x, y, z	Point coordinates. If y and/or z are not given, their value is set to 0. This can be the case for 1-D and 2-D.
      h	Mesh size around the point.

    • Keyword curve defines a curve (or line):
      curve label=<n> [line=<n1>,<n2>] [circle=<n1>,<n2>,<n3>]
      Here the second and the third argument are exclusive.

      n	Label of curve.
      n1, n2	Labels of points defining a line.
      n1, n2, n3	Labels of points defining a circular arc, n1 and n2 are the two points defining the extremities of the arc and n3 is the point defining the center of the circular arc.

    • Keyword contour defines a contour as an assembly of curves:
      contour label=<n> curve=<c1>,<c2>,...

      n	Label of contour.
      c1, c2, ...	Labels of curves defining the contour.

    • Keyword surface defines a surface as delimited by curves:
      surface label=<n> contours=<c1>,<c2>,...

      n	Label of surface.
      c1, c2, ...	Labels of contours defining the surface.

    • Keyword volume is under development.
    • Keyword code enables assigning codes to various entities of the geometry, and then of the generated mesh:
      code value=<v> [points=<p1>,<p2>,... | curves=<c1>,<c2>,... | surfaces=<s1>,<s2>,... | volumes=<v1>,<v2>,...] 
      Here above, exactly one list must be given: points, curves, surfaces or volumes.

      v	Code value (integer) to assign to an entity.
      p1, p2, ...	Points to which the code v is assigned.
      c1, c2, ...	Curves to which the code v is assigned.
      s1, s2, ...	surfaces to which the code v is assigned.
      v1, v2, ...	Volumes to which the code v is assigned.

    • Keyword nbdof enables generating a finite element mesh using the constructed geometry:
      nbdof n
      n is the number of degrees for freedom for each support of degrees of freedom (e.g. nodes). The default value is 1.
    • Keyword list outputs a list of all generated entities in mesh.
    • Keyword generate enables generating a finite element mesh using the constructed geometry.
    • Keyword clear erases all constructed material since the beginning of geometry description.
    • Keyword save saves the generated mesh in a file:
      save file
      file is the name of the file in which the mesh is stored.
    • Keyword read reads an already existing mesh from a file:
      read file
      file is the name of the file in which the mesh is read.
  • grid: Constructs a uniform grid of an interval (in 1-D), a rectangle (in 2-D) or a cube (in 3-D):
    grid [name=<nm>] x=<mx>,<Mx> [y=<my>,<My>[z=<mz>,<Mz>]]  [ne=<nx>[,<ny>,<nz>]]

    nm	Name of grid. This argument is optional.
    mx, my, mz	Minimal value of the intervals: The gridded domain is defined by (mx,Mx)*(my,My)*(mz,Mz). If the parameters my and mz are absent, the domain is the interval (mx,Mx) and if only mz is absent, the domain is the rectangle (mx,Mx)*(my,My).
    Mx, My, Mz	Maximal value of the intervals: The gridded domain is defined by (mx,Mx)*(my,My)*(mz,Mz). If the parameters My and Mz are absent, the domain is the interval (m1,M1) and if only Mz is absent, the domain is the rectangle (mx,Mx)*(my,My).
    nx, ny, nz	Subdivision of the grid, nx (resp. ny, nz) is the number of intervals in the x (resp. y, z) direction. The default value of these parameters is 10.

  • Command function enables defining a function by its analytical expression.
    Synopsis:
    function [name=<nm>] var=<v> [nb=<n>]  definition=<d>
    

    nm	Name of function. This argument is optional, but a name of a function is the only way to retrieve it.
    v	Name of variable. In the case of a multivariable function, the name of variables is defined by v1, v2, ...
    n	Number of variables. By default this value is 1.
    d	String defining an expression of the function definition. If the string must contain blank spaces, it must enclosed in ". This argument is mandatory.

  • Command sample enables sampling a function i.e. defining its value on a given grid or mesh. The user must provide each a number of sampling points, a grid or a mesh. In the first cas, a grid is automatically created.
    Synopsis:
    sample function=<f> [nb=<nx>[,<ny>,<nz>]] [x=<mx>,<Mx>]  [y=<my>,<My>] [z=<mz>,<Mz>] [grid=<g>] | [mesh=<ms>] [vector=<v>]
    

    f	Name of a defined function. This argument is mandatory.
    nx	Number of sampling points in the x-direction
    ny	Number of sampling points in the y-direction if this is a 2-D or 3-D case
    nz	Number of sampling points in the z-direction if this is a 3-D case
    mx, Mx	Minimum and maximum coordinates in the x-direction
    my, My	Minimum and maximum coordinates in the y-direction if this is a 2-D or 3-D case
    mz, Mz	Minimum and maximum coordinates in the z-direction if this is a 3-D case
    g	Name of a defined grid on which the function f is evaluated. The number of variables must be at least equal to the space dimension.
    ms	Name of a defined mesh on which the function f is evaluated. The number of variables must be at least equal to the space dimension.
    v	Name of the vector to create that contains the sampling. This argument is mandatory.

  • Command plot enables plotting various types of data.
    Synopsis:
    plot [function=<f> | tabulation=<t> | vector=<v> | history=<h> | mesh=<ms>] [x=<m>,<Mx>] [y=<my>,<My>]
        [log=<lx>,<ly>]  [titre=<ti>] [label=<l>] [use=<u>] [component=<c>]

    f	Function name to plot. Note that only one-variable functions can be plotted with this argument.
    t	Name of tabulation to plot.
    v	Vector name to plot. Only vectors associated to a mesh can be plotted.
    h	Name of history vector to plot. If vector contains more than one value per time step to plot, the first component is plotted. Otherwise, a value of the argument component must be specified.
    ms	Mesh to plot.
    mx, Mx	Minimum and maximum value for the x-axis. This argument is useful for the case of graph of a function only.
    my, My	Minimum and maximum value for the y-axis. This argument is useful for the case of graph of a function only.
    lx, ly	Switches (0 or 1) to choose a logarithmic scale for the x and axes respectively.
    ti	Title of plot.
    l	Label of curve.
    u	Software for plotting. Must be gnuplot (Default), or gmsh if available.
    c	Component label to plot for a vector with multiple components at each abcissa value (Default: 1).

  • Command history enables choosing a vector to store in a history vector.
    Synopsis:
    history <v> <h>
    It means that each time step (according to a frequency setting) is performed in a calculation, the vector with name v will be added to the history vector h.
  • Command data has no argument. It displays all defined data and entities.
  • Command list is useful to output a chosen type or entity.
    Synopsis:
    list <s>
    where s must be one of the values:
    param, grid, mesh, vect, hvect, funct, tab, matrices, ls, algebraic, ode, pde, optimization, eigen.
  • Command remove enables removing a given data or entity. Note that no memory is released when removing but the entity cannot be used any more after removing, and its name can be used for another datum.
    Synopsis:
    remove <name>
    where the argument is the name of the entity to remove.
  • Command rename enables changing a data or an entity name.
    Synopsis:
    rename <n1> <n2>
    where n1 is the old name and n2 is the new one.
  • Command description enables defining a string as a description of any given data or entity.
    Synopsis:
    description  <s>
    where s is the string defining the description.
  • Command = or print is useful to output a chosen data or entity. The command
    = <s>
    outputs the entity s.
  • Command save enables saving a datum or entity in a specified file.
    Synopsis:
    save name=<nm> file=<f> [format=<fo>] [every=<e>]
    

    nm	Name of data. Note that only vectors, matrices, history vectors, meshes or grids can be saved in files.
    f	File name where data are to ne saved..
    fo	Format of file. This format is to be chosen among the values: ofeli, gnuplot, vtk, tecplot, matlab. Note that all formats are not available for all data. The default is the ofeli format.
    e	Frequency of saving data for the case of history vector saving. The default value is 1.

• Solver commands

  Here is the list of available solver commands:
  algebraic, ode, pde, optim, eigen, integration, approximation, solve,

  • Command algebraic defines an algebraic equation (or system of equations) to solve by a numerical method. It can be given either by a short or an extended form.
    In its short version the command synopsis is:
    algebraic [size=<n>] [function=<f> | definition=<d>] [var=<x>]  [nls=<m>]

    n	Size of the system of algebraic equations. Default size is 1.
    f	Name of an already defined function (Functions can be defined in data). For a system, this argument must be repeated as many times as the number of equations.
    d	Expression defining a function. For a system, this argument must be repeated as many times as the number of equations.
    x	Name of the variable. If the size is greater than 1 (a system), the unknowns are x1, x2, ... This argument is unnecessary in the case where a defined function is used (The variable name is the one of that function), but mandatory otherwise.
    m	Iterative method to solve the system. This is a string to choose among the values bisection, regula-falsi, secant, newton. Note that the methods bisection and regula-falsi are to be used for the case of a unique equation. The default method is newton.

    In its extended version, the command algebraic has no arguments, but rather initiates a submenu with the available keywords:
    size, function, definition, jacobian, init, variable, nls

    • size <n>
      n is the algebraic system's size. The default value is n=1.
    • function <s>
      s is a string giving the name of an existing function (Functions can be defined in data). For a system, this argument must be repeated as many times as the number of equations.
    • definition <s>
      s is a string defining analytically a function. Note that if the string contains blank spaces it must be surrounded by ". For a system, this argument must be repeated as many times as the number of equations.
    • jacobian <y1> <y2> <y3> ...
      y1, y2, ... are the partial derivatives of a function of the system. The keyword jacobian must be called for each function of the system in their natural order. By default the values of the jacobian are computed analytically from the expression of the functions.
    • init <y1> <y2> <y3> ...
      y1, y2, ... are initial guesses of the solution components.
    • variable <x>
      x is the name of the variable (or vector). This keyword is mandatory if the keyword definition is used. If the size of the system is greater than 1, the unknowns are necessarily x1, x2, ...
    • nls <s>
      s is a string defining an iterative method to solve the nonlinear system. The default value is newton. The string s is to be chosen among the values bisection, regula-falsi, secant, newton. Note that the methods bisection and regula-falsi are to be used for the case of a unique equation.

  • Command ode defines an ordinary differential equation (or system of ordinary differential equations) to solve by a numerical method. It can be given either by a short or an extended form.

    In its short version the command synopsis is:
    ode [size=<n>] [function=<f> | definition=<d>] [var=<x>]  [initial=<v1>,<v2>,...] [final-time=<ft>] [time-step=<ts>]
        [scheme=<s>]

    n	Size of the system of ode's. Default size is 1.
    f	Name of an already defined function (Functions can be defined in data). For a system, this argument must be repeated as many times as the number of differential equations.
    d	Expression defining a function. For a system, this argument must be repeated as many times as the number of differential equations.
    y	Name of the variable, other than the time variable, which is necessarily t. If the size is greater than 1 (a system), the unknowns are y1, y2, ... This argument is unnecessary in the case where a defined function is used (The variable name is the one of that function), but mandatory otherwise
    v1, v2, ...	Initial condition values.
    ft	Final (or maximal) time value. The default value of this parameter is 1.
    ts	Time step value. The default value of this parameter is 0.1.
    s	Time integration scheme. This is a string to choose among the values: forward-euler, backward-euler, crank-nicolson, heun, newmark, leap-frog, AB2 (Adams-Bashforth, 2nd Order), RK4 (Runge-Kutta, 4th Order), RK3-TVD (Runge-Kutta, 3rd order, TVD), BDF2 (Backward Difference Formula, 2nd Order). The default value for this argument is backward-euler.

    In its extended version, the command ode has no arguments, but rather, it initiates a submenu with the available keywords:
    size, function, definition, variable, jacobian, initial, final-time, time-step, scheme

    • size <n>
      n is the ode system's size. The default value is n=1.
    • function <s>
      s is a string giving the name of an existing function. For a system, this argument must be repeated as many times as the number of equations.
    • definition <s>
      s is a string defining analytically a function. Note that if the string contains blank spaces it must be surrounded by ". For a system, this argument must be repeated as many times as the number of equations.
    • jacobian <y1> <y2> <y3> ...
      y1, y2, ... are the partial derivatives of a function of the system. The keyword jacobian must be invoked for each function of the system in their natural order. By default the values of the jacobian are computed analytically from the expression of the functions.
    • initial <y1> <y2> <y3> ...
      y1, y2, ... are initial guesses of the solution components.
    • variable <y>
      y is the name of the variable (or vector) other than the time variable, which is necessarily t. This keyword is mandatory if the keyword definition is used. If the size of the system is greater than 1, the unknowns are necessarily y1, y2, ...
    • scheme <s>
      s is a string defining Time integration scheme. This is a string to choose among the values: forward-euler, backward-euler, crank-nicolson, heun, newmark, leap-frog, AB2 (Adams-Bashforth, 2nd Order), RK4 (Runge-Kutta, 4th Order), RK3-TVD (Runge-Kutta, 3rd order, TVD), BDF2 (Backward Difference Formula, 2nd Order). The default value for this argument is backward-euler.
  • Command pde defines a partial differential equation (or system of partial differential equations) to solve by a numerical method. Due to its long list of arguments, this command is available in extended version only.
    The command pde has one argument:
    pde <eq>
    eq is a string defining the pde to solve. In the current release, the following pde's are available:

    • linear: For the Laplace equation, with a right-hand side, in 1-D, 2-D and 3-D.
    • laplace: For the Laplace equation, with a right-hand side, in 1-D, 2-D and 3-D.
    • heat: For the heat equation, in 1-D, 2-D and 3-D.
    • wave: For the wave equation, in 1-D, 2-D and 3-D.
    • linear-elasticity: For linearized elasticity equations, in 2-D and 3-D.
    • truss: For the planar truss problem in structural mechanics.
    • beam: For the 3-D beam problem in structural mechanics.
    • incompressible-navier-stokes: For 2-D and 3-D transient incompressible Navier-Stokes equations.

    Other equations are available but not sufficiently tested.
    Then a submenu is initialized with the available keywords:
    vector, coef, init, bc, bf, sf, space, ls

    • variable <u>
      u is a string defining a vector (vector of unknowns) for the equation. If the vector has been defined already, this one will be used. If not, the new vector will be added to the list of vectors. This argument has to be given as many times as the equation requires it (e.g. Incompressible Navier-Stokes equations need 2 vectors: velocity and pressure).
    • coef <c> <v>
      To define various coefficients of the pde. These coefficients can be functions of position and time. Here c is the name of the coefficient and v is a regular expression defining a function of position x, y, z and time t. The coefficient are the physical properties involved in partial differential equations. These coefficients has to be chosen among the values:
      
      • density or rho: This is involved in various pde's like the heat equation, fluid dynamics, ...
      • Cp or specific-heat: Involved in thermal equations.
      • kappa or thermal-conductivity: Involved in thermal equations.
      • Mu or magnetic-permeability: Involved in electromagnetics.
      • sigma or electric-conductivity: Involved in electromagnetics.
      • mu or viscosity: Involved in fluid dynamics.
      • epsilon or electric-permittivity: Involved in electromagnetics.
      • omega or angular-frequency: Involved in time harmonic formulations.
      • beta or thermal-dilatation: Involved in fluid dynamics.
      • v or velocity: Involved in transport equations.
      • young: Involved in solid and structural mechanics.
      • poisson: Involved in solid and structural mechanics.
    • init value=<v>
      to prescribe an initial condition. Here v is either a constant real number to assign to initial solution or a string defining a regular expression as function of x, y, z, t, space and time coordinates.
    • bc code=<c> value=<v>
      to prescribe a (Dirichlet) boundary condition. Here c is the code for which the condition is prescribed, v is either a constant real number to prescribe or a string defining a regular expression as function of x, y, z, t, space and time coordinates.
    • bf value=<v>
      to define a source or body force term. Here v is either a constant real number to assign to the right-hand side of the pde or a string defining a regular expression as function of x, y, z, t, space and time coordinates.
    • sf code=<c> value=<v>
      to prescribe a surface force (or a traction or a flux) term. Here c is the code for which the condition on sides (edges or faces) is prescribed, v is either a constant real number to prescribe or a string defining a regular expression as function of x, y, z, t, space and time coordinates.
    • space <m>
      m is the chosen space discretization method. This string is to be chosen among the values: fd (Finite Differences), feP1 (P₁ Finite Elements), feP2 (P₂ Finite Elements), feQ1 (Q₁ Finite Elements), fv (Finite Volumes). An error will be issued if the chosen method is not implemented in ofeli.
    • ls <s> <p>
      s is the solver of the resulting linear system. This string is to choose among the values direct, cg, cgs, bicg, bicg-stab, gmres. Moreover, p is the preconditioner if an iterative solver is chosen. This string is to pick among the values: ident, diag, dilu, ilu, ssor.
    • phase <p> [c]
      This sub-command enables computing phase of a particular component of solution and store it in a history vector with name p. The solution component is c. It default value is 1.
  • Command optim defines and solves an optimization problem.
    It can be given by a short or an extended form.

    In its short version the command synopsis is:
    optim [size=<n>] [function=<f>] [objective=<d>] [lp]  [gradient=<g1>,<g2>,...]  [low-bound=<i>,<lb>]
         [up-bound=<j>,<ub>] [variable=<x>] [algorithm=<a>]

    n	Number of optimization variables. Default value is 1.
    f	Name of an already defined function as the objective function to mimimize (Functions can be defined in data).
    d	Expression defining the objective function to minimize.
    lp	Toggle to say if we are dealing with the linear programming problem. By default, we are considering a nonlinear objective function.
    g1, g2, ...	Partial derivatives of the objective function defined analytically. By default the partial derivatives are computed analytically from the expression of the objective function.
    i, lb	Enables prescribing a lower bound constraint, i.e., here we can impose x(i)≥lb. It must be used once for each bound constraint.
    j, ub	Enables prescribing an upper bound constraint, i.e., here we can impose x(j)≤ub. It must be used once for each bound constraint.
    x	Name of the variable (or vector). This keyword is mandatory if the keyword definition is used. If the size of the system is greater than 1, the unknowns are necessarily x1, x2, ...
    a	String defining the used optimization method. This string is to pick in the following values: gradient, truncated-newton, simulated annealing, nelder-mead, newton. The default value of this parameter is gradient.

    It can be noticed that there is no way to impose other constraints than bound constraints in the short menu version. For this one must resort to the extended version.

    In its extended version, the command optim has no arguments, but rather, it initiates a submenu with the available keywords:

    • size <n>
      Number of optimization variables. Default value is 1.
    • function <f>
      f is the name of an already defined function as the objective function to mimimize (Functions can be defined in data).
    • objective <f>
      f is an expression defining the objective function to minimize.
    • lp
      This keyword is a toggle to say if we are dealing with a linear programming problem. By default, we are considering a nonlinear objective function
    • gradient <g1> <g2> ...
      g1, g2, ... are the partial derivatives of the objective function defined analytically. By default the partial derivatives are computed analytically from the expression of the objective function.
    • hessian <h1> <h2> ...
      h1, h2, ... are the partial derivatives of the gradient defined analytically. This keyword must be called once for each optimization variable. By default the hessian is computed analytically, if the optimization algorithm needs it, from the expression of the objective function.
    • low-bound <i> <lb>
      To prescribe a lower bound constraint, i.e., we can impose x(j)≥lb. It must be used once for each bound constraint.
    • up-bound <j> <ub>
      To prescribe an upper bound constraint, i.e., we can impose x(j)≤ub. It must be used once for each bound constraint.
    • ge-constraint <arg>
      This keyword is available in the linear programming case only. For this, arg is a list:
      v(1) v(2) ... v(n) v(n+1)
      to impose v(1)*x(1) + v(2)*x(2) + ... + v(n)*x(n) ≥ v(n+1)
    • le-constraint <arg>
      The arguments of this keyword depend on the case whether we have a linear programming problem or not.
      • In the linear programming case arg is a list:
        v(1) v(2) ... v(n) v(n+1)
        to impose v(1)*x(1) + v(2)*x(2) + ... + v(n)*x(n) ≤ v(n+1)
      • In other cases, the keyword has only one argument: the analytical expression of the function we want to impose to be nonpositive.
    • eq-constraint <arg>
      The arguments of this keyword depend on the case wether we have a linear programming problem or not.
      • In the linear programming case arg is a list:
        v(1) v(2) ... v(n) v(n+1)
        to impose v(1)*x(1) + v(2)*x(2) + ... + v(n)*x(n) = v(n+1)
      • In other cases, the keyword has only one argument: the analytical expression of the function we want to impose to be zero.
    • penalty <p>
      p is the value of the penalty parameter. Constraints are enforced by a penalty formulation except for linear programming problems.
    • variable <x>
      Name of the variable (or vector). This keyword is mandatory if the keyword definition is used. If the size of the system is greater than 1, the unknowns are necessarily x1, x2, ...
    • initial <x1> <x2> ...
      x1, x2, ... are prescribed initial values of optimization variables.
    • algorithm <a>
      a is a string defining the used optimization method. This string is to pick in the following values: gradient, truncated-newton, simulated annealing, nelder-mead, newton. The default value of this parameter is gradient.
  • Command eigen enables solving an eigenvalue problem.
    Synopsis:
    eigen matrix=<M> [symmetric] [method=<a>]  [nb=<n>] [eigv] [evec=<p>]

    M	Name of an already defined matrix.
    symmetric	Switch to say that matrix is symmetric. By default, the matrix is assumed unsymmetric.
    a	Method for extraction of eigenvalues. It must take one of the values subspace or qr.
    n	Number of eigenvalues to extract. By default, all eigenvalues are extracted.
    eigv	Switch to compute eigenvectors as well. By default, eigenvectors are not computed. Except for some methods where this is done automatically.
    p	Prefix of names of eigenvectors.

  • Command integration performs numerical integration of a given function over a given domain.
    In the present release, only integrals over an interval are handled.
    Synopsis:
    integration function=<f> [definition=<d>]  [var=<v>] [interval=<mx>,<Mx>] [ne=<n>] [formula=<m>]

    f	Name of an already defined function.
    d	Expression defining a function.
    v	Name of the variable.
    mx, Mx	Values of extremities of the integration interval.
    n	Number of subdivisions of the integration interval. Default value is 10.
    m	Numerical integration formula. The possible choices are left-rectangle, right-rectangle, mid-point, trapezoidal, simpson, gauss-legendre, gauss-lobatto. For the Gauss formulae, the number of points can be specified by typing gauss-legendre,2 for instance.

  • Command approximation enables solving data approximation problems.
    The command has an extended form only, with the following submenu:

    • lagrange tabulation=<t>|file=<f> [function=<fct>]
      For Lagrange interpolation. Here t is the name of a defined tabulation, f is the name of a file from which the tabulated points are to be read, fct is the (optional) name to give to the resulted polynomial Lagrange function. Note that the degree of the resulting polynomial is deduced from the tabulation size.
    • fitting tabulation=<t>|file=<f>  degree=<d>|basis=<b₁,b₂...>  [function=<fct>]
      For least-square fitting. Here t is the name of a defined tabulation, f is the name of a file from which the tabulated points are to be read, d is the degree of the fitting polynomial if such an approximation is chosen. Otherwise one can provide a basis of spanning functions of the fitting function. fct is the (optional) name to give to the resulted fitting function.
    • bezier file=<f>|vertices=<v>  [nc=<ncu>[,<ncv>]] np=<npu>[,<npv>]  [vector=<ve>]
      For Bézier approximation. Here one can choose either a list of given vertices of control polygon v (3 components for each point) or the same list to be read from a file f. ncu (resp. ncv for the case of a surface approximation) is the number of control vertices in the u-direction (resp. v-direction). ve is the resulting vector of Bézier approximation. If this vector name is not provided, the application attributes a name that is communicated.
    • bspline file=<f>|vertices=<v> [order=<o>]  [nc=<ncu>[,<ncv>]] np=<npu>[,<npv>]  [vector=<ve>]
      For Bspline (Basis Spline) interpolation. Here one can choose either a list of given vertices of control polygon v (3 components for each point) or the same list to be read from a file f. o is the order of the Bspline interpolation (By default: 2). ncu (resp. ncv for the case of a surface approximation) is the number of control vertices in the u-direction (resp. v-direction). ve is the resulting vector of Bspline interpolation. If this vector name is not provided, the application attributes a name that is communicated.
    • nurbs file=<f>|vertices=<v> [order=<o>]  [nc=<ncu>[,<ncv>]] np=<npu>[,<npv>]  [vector=<ve>]
      For NURBS (Non Uniform Rational Basis Spline) approximation. Here one can choose either a list of given vertices of control polygon v (3 components for each point) or the same list to be read from a file f. o is the order of the Bspline interpolation (By default: 2). ncu (resp. ncv for the case of a surface approximation) is the number of control vertices in the u-direction (resp. v-direction). ve is the resulting vector of NURBS approximation. If this vector name is not provided, the application attributes a name that is communicated.
  • Command solve enables solving one or more defined problems. Note that commands integration and approximation do not need the command solve to be solved. They solve directly the invoked command.
    The command solve can be used either in short or extended version. For the short form, the synopsis is:
    solve [problem=<p1>,<p2>,...] [analysis=<a>]
    

    p1, p2, ...	List of names of problems to solve
    a	Analysis type. This string is to choose among the values: stationary, transient, eigen, optimization. Note that in most cases, this value is automatically assigned in function of the defined problem(s).

    For the extended version, the command solve has the following submenu:

    • problem <p>: Add problem with name p to the list of problems to solve.
    • analysis <a>: Analysis type. This string is to choose among the values: stationary, transient, eigen, optimization. Note that in most cases, this value is automatically assigned in function of the defined problem(s)

  Calculator

  rita can be used as a simple calculator to manipulate various data. For this, calculator instructions can be introduced just like any other command.
  Let us illustrate this through some examples:
  

  • x = 10
  • y = 2*x - exp(x)
  • z = y^2 - sin(pi*x)

  In these examples we have defined 3 variables x, y and z. They are stored in rita as parameters.
  Here is another series of examples:
  

  • v = { 1.0, -2.0, 6.0 }
  • u = vector(3)
  • u[2] = -5
  • z = v*u
  • B = u*v
  • A = matrix(2,3)
  • A[0,1] = -2.0
  • A[1,2] = 5.0
  • = A
  • w = A*v'
  • =w

  Here above, v is a row vector as defined, u is a column vector. So that z is a scalar while B is a 3x3-matrix.
  A is a 2x3-matrix initialized by 0. We also modify some entries of the matrix. Note that the indices here start with 0. We can check the contents of A by ouputting it (we can use either = or print for this end). Next, a vector w is defined as the product of A by the transpose of v (which is a column vector). We finally output w.

RITA License

rita is freely available under the GPL (Gnu Public License).
Copyright © 2021-2024 Rachid Touzani

rita is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
rita is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.

Downloading

rita is available in the OFELI package. Once OFELI is installed, rita is available as an executable application.
The whole package can be downloaded from here.