Basic types

Caution

If you are not familiar with C++ syntax, we recommend you to see C++ syntax before reading this page.

Integers: Int, Dimen and Number

To define integers, XLiFE++ provided three types:

Int: it represents a signed integer with 32 or 64 bits encoding respectively on 32 or 64 bits computers, whatever the OS. More precisely, it is an alias of long int in 32 bits or long long int in 64 bits.

Dimen: it represents a short unsigned int.

Number: it represents an unsigned integer with 32 or 64 bits encoding respectively on 32 or 64 bits computers, whatever the OS. More precisely, it is an alias of size_t.

As a result, Int and Number follows both the OS architecture. This choice is made in header file config.hpp automatically.

Booleans

To define booleans, you may use the standard C++ type bool.

Floats: Real and Complex

To define floats, XLiFE++ provides Real. It is a nice datatype allowing to deal with floats, whatever the precision. Real is no more than an alias to float, double or long double; this choice is made in the config.hpp header file by setting option PREC_TYPE to one of the following value: STD_TYPES, LONG_TYPES (the default) or LONG_LONG_TYPES.

Caution

When you change the macro, all the library has to be rebuilt!

Complex is no more than an alias to std::complex<Real>.

String extensions

String is a nice class allowing to deal with char of arrays without managing the memory. String is no more than an alias to the string class of the STL which is either standard string (utf8, by default) or wide string (utf16); this choice is made in the config.hpp header file by setting the option STRING_TYPE to STD_STRING (the default) or WIDE_STRING.

Caution

When you change the macro, all the library has to be rebuilt!

As a result, String proposes all the functionalities of std::string. Mainly, you can create, concatenate string, access to char and find string in string:

String s1("a string");      // create a String
String s2="another string"; // create a String using =
String s12=s1+" and "+s2;   // concatenate String, s3="a"+"b" does not work!
s1+=" and "+s2;             // concatenate String, now s1 is the same as s12
int l=s1.size();            // number of char of s1, s1.length() gives the same
char a=s1[3];               // char a='t' (the fourth character)
s1[3]=p;                    // now s1="a spring and another string";
int p=s1.find("string",0);  // find first position of "string" from beginning (if p=−1 not found)
s1.replace(p, 5, "spring"); // replace "string" by "spring"
s2=s1.substr(p, 5);         // extract string of length 5 from position p
s1.compare(s2);             // alphanumeric comparison, return 0 if equal,
                            // a negative (positive) value if s1<s2 (s1>s2)
char * c=s1.c_str();        // return pointer to the char array of the string

There is a lot of variations of these string functions and other functions; see the STL documentation. XLiFE++ provides additional string utilities:

template <typename T_>  String tostring(const T_& t); // 'anything' to String
template <typename T_>  T_ stringto(const String& s); // String to 'anything'
String lowercase(const String&);   // converts to lowercase
String uppercase(const String&);   // converts to uppercase
String capitalize(const String&);  // converts initial char to uppercase
String trimLeading(const String&); // trims leading white space
String trimTrailing(const String&);// trims trailing white space
String trimSpace(const String&);   // trims leading and trailing white space
String delSpace(const String& s);  // deletes all white space from String
int findString(const String, const std::vector<String>&); // search capabilities

Be cautious with template conversion functions. The template T_ type has to be clarified when invoking stringto.

// examples of conversion stringto
String s="1 2 3";
int i=stringto<int>(s);         // i=1
Real r=stringto<Real>(s);       // r=1.
Complex c=stringto<Complex>(s); // c=(1.,0)
void * p=stringto<void*>(s);    // p=0x1
String ss=stringto<String>(s);  // ss="1"
s="(0,1)";
c=stringto<Complex>(s);         // c=(0.,1.)

The Point class

A finite element library deals obviously with points. The purpose of the Point class is to deal with points in any dimension and providing some algebraic operations on points and comparison capabilities. It inherits from std::vector<Real> class and it is used by the Function class encapsulating user functions.

There are many ways to construct a point:

Point p4(4, 0.);      // dimension(4) and value(0) p1=(0, 0, 0, 0)
Point p1(2.);         // a 1D point p1=(2);
Point p2(1., 0.);     // a 2D point p1=(1,0);
Point p3(1., 0., 1.); // a 3D point p1=(1,0,1);
Point p4{1.,2.,3.};   // initialisation list
Point p4={1.,2.};     // alternate syntax
Real v[]={1, 2, 3};   // array of Real
Point p5(3, v);       // dimension and Real array
Reals w(3, 0);        // the std::vector<Real> (0,0,0)
Point p6(w);          // stl vector

To access to:

• the dimension n of a point p: p.size(),

• to the i-th coordinate (\(1\le i\le n\)) of a point p: p(i) or p[i-1]

• to the x, y or z coordinate (restricted to \(ǹ\le 3\)): p.x(), p.y() or p.z()

• the vector storing the point: p.toVect();

You can use the coordinate accessors in reading or writing mode. A simple example:

Point p(1., 0., 1.); // a 3D point p=(1,0,1);
p(1)=2;              // modify the first coordinate
p.y()=3.;            // modify the second coordinate
Reals v=p.toVect();  // convert point to vector

Using standard operators (+=, -=, +, -, * and /), it is possible to perform algebraic computations on points up to linear combinations:

Point p(1., 0., 1.), q(0., 0., 1.), r(1., 2., 3.); // some 3D points
Point g=(p+q+r)/3;  // compute the barycenter of p, q, r
(p+=q)/=2;          // p contains the middle of p and q

Besides, there are some functions to compute the distance or the square of distance between two points:

Point p(1., 0., 1.), q(0., 0., 1.), r(1., 2., 3.); // some 3D points
Real d=p.distance(q);   // compute distance between p and q
d=pointDistance(p, q);  // alternative syntax
d=p.squareDistance(q);  // square of the distance between p and q
d=squareDistance(p, q); // alternative syntax

Comparing points is possible using standard operators ==, !=, <, >, <= or >=. The comparison uses a tolerance factor \(\tau\) defined by the variable xlifepp::Point::tolerance (p, q being points of \(\mathbb{R}^n\)):

\[\begin{split}\begin{aligned} p == q & \iff |p-q|\le \tau \\ p < q & \iff \exists i \le n, \text{such that } \begin{cases} \forall j < i, |p_j-q_j| \le \tau \\ p_i < q_i - \tau \end{cases} \end{aligned}\end{split}\]

The other comparison operators !=, >, <= or >= are naturally defined from == and < operators. By default, the tolerance is set to 0. Below is an example:

Point p(1., 0., 1.), q(0., 0., 1.); // some 3D points
bool r=(p==q);                      // r=false
r=(p!=q);                           // r=true
r=(p<q);                            // r= false
Real eps=.00001;                    // tolerance factor
Point::tolerance=eps;               // change the tolerance factor to eps
r=(p==(p+eps/2));                   // r=true

Geometrical transformations on points work as on geometries. Please see section Geometrical transformations for definition and use of transformations routines.

Then, if you want to create a new Point by applying a transformation on a Point, you should use one of the dedicated external functions. For instance:

Point p1;
Point p2=translate(p1, _direction={0., 0., 1.});

Then, if you want to apply a transformation and modify the input object, you can use one of the following external functions: translate(), rotate2d(), rotate3d(), homothetize(), pointReflect(), reflect2d(), reflect3d().

Identified as a vector, Point provides the following operation:

operation	syntax	comment
dot	Real dot(Point, Point)	inner product
cross product	Point crossProduct(Point, Point)	cross product of 2 points
mixed product	Real mixedProduct(Point, Point, Point)	mixed product (AxB).C
2D cross product	Real crossProduct2D(Point, Point, Point)	cross product BAxCA as real
3D cross product	Point cross3D(Point, Point)	cross product AxB
orthogonal point	Point orthogonalPoint3D(Point P)	Q s.t. OQ.OP=0

The following coordinate changes are available:

operation	syntax	comment
to polar	Point toPolar(Point)	Point to polar/cylindrical coordinates
to spherical	Point toSpherical(Point)	Point to spherical coordinates
to 2D elliptical	Point toEllipticCoordinates(Point P, Point C, Point A1, Point A2)	elliptical coordinates related to the ellipse (C,A1,A2)
to 3D elliptical	Point toEllipticCoordinates(Point P, Point C, Point A1, Point A2, Point A3)	(r,theta,phi) related to the ellipsoid (C,A1,A2,A3)
to barycentric	Point toBarycentric(Point M, Point S1, Point S2,  [Point S3], [Point S4])	barycentric coordinates related to segment, triangle or tetrahedron

A lot of geometrical tools are available (see API for usage):

category	functions
check in	arePointsCoplanar(), isPointInSegment(), isPointInTriangle(), isPointInQuadrangle(), isSegmentInSegment(), isSegmentInTriangle(), isSegmentInQuadrangle(), isTriangleInTriangle(), isTriangleInQuadrangle()
check intersection	doesSegmentCrossesSegment(), doesSegmentCrossesQuadrangle(), doesSegmentIntersectsTriangle(), doesSegmentIntersectsQuadrangle(), doesTriangleIntersectsTriangle(), doesTriangleIntersectsQuadrangle(), doesQuadrangleIntersectsQuadrangle()
intersection	intersectionOfStraightLines(), intersectionOfPlanes(), intersectionHalfLineSegment(), intersectionHalfLinePolygon(), intersectionHalfLineEllipse(), intersectionOfPlanesWithOneSharedPoint(), intersectionOfSegments(),
projection	projectionOnStraightLine(), projectionOfPointOnPlane(), projectionOfSegmentOnPlane(), projectionOfTriangleOnPlane(), projectionOnSegment(), projectionOnTriangle(), projectionOnQuadrangle(), projectionOnTetrahedron()
various	nonSeparatingEdge(), outwardNormalsOfTriangle(), signedDistancesToTriangleEdges(), commonPerpendicularOfStraightLines(), eqtOfPlane(), triangleEdgesLengths(), triangleHeightsLengths(), trihedralOrientation() splitInTriangles(), convexHull2D()

The Collection class

The aim of collection objects (inheriting from the template base class Collection, and behaving like a C++ std::vector) is to provide additional ways to construct them from a set of values, even in old C++ standards.

XLiFE++ provides 4 classes managing collections of Int, of Number, of String and of Point. Their names are Ints, Numbers, Strings and Points.

Numbers nv(1, 2, 3, 4, 5); // constructor from 5 values, you can set up to 48 values
Ints iv={-1, 3, 4, -2};    // constructor from initializer_list
Strings sv(10, "Gamma");   // constructor from size and common values
Points ptv(5, Point(0.,1.));
sv << "Omega";             // push back a new element to the collection
theCout << nv[2] << eol;   // accessing to an element
Point p=ptv(3);
theCout << ptv << eol;

Note

For advance usage, there exists also the PCollection<T> class that handles a collection of T*.

The Parameter and Parameters classes

XLiFE++ provides the Parameter class to encapsulate different kind of value: Int, Real, Complex, String, bool, void*; the last type allowing to handle anything by pointer. A Parameter object is constructed from a value and a name. Additional shortnames can be set.

Parameter pi(1, "i");                // definition from an integer
Parameter pr(2.5, "r");              // definition from a Real
Parameter pc(Complex(0.5,1.2), "c"); // definition from a Complex
Parameter pb(true, "b");             // definition from a boolean
Parameter ps("string","s");          // definition from a String
Point p(1.,2.); Parameter pp(p, "p");// definition from a Point

Shadowing the pointer type, it is also possible to instanciate Parameter object from std::vector<T> (with T a Int, Number, Real, Complex, String, bool, Point), from Matrix<T> (with T a Real, Complex), from a Point. Other XLiFE++ objects can also be handle (Function, Parametrisation, GeomDomain, IntegrationMethod, TermVectors).

std::vector<Real> v={1.,3.,5.,7.,9.};
Parameter pv(v, "odds");                // definition from a vector

A Parameter associates the value to encapsulate to a string. This string is useful in the context of sets of Parameter. The dedicated object is Parameters, that behaves like an unordered hashtable.

Parameter p(2.5, "k");                // Parameter from a Real value
Parameters pars;                      // list of Parameter
pars << p;                            // inserting a Parameter into list
Real k=pars("k");                     // getting a parameter from list
std::vector<Real> v={1.,3.,5.,7.,9.};
pars << Parameter(v,"odds");          // inserting on fly a parameter into list

Warning

Be cautious when retrying the parameter value, the variable type must be consistent with the parameter type.

The key-value system that will be explained for most user objects relies on class Parameter, whereas functions involved in (bi)linear forms rely on and Parameters.