# 17. `simple` — Predefined geometries with a simple shape.

This module contains some functions, data and classes for generating Formex structures representing simple geometric shapes. You need to import this module in your scripts to have access to its contents.

## 17.1. Functions defined in module simple

`simple.``shape`(name)

  Return a Formex with one of the predefined named shapes.

  This is a convenience function returning a plex-2 Formex constructed from one of the patterns defined in the simple.Pattern dictionary. Currently, the following pattern names are defined: ‘line’, ‘angle’, ‘square’, ‘plus’, ‘cross’, ‘diamond’, ‘rtriangle’, ‘cube’, ‘star’, ‘star3d’. See the Pattern example.

`simple.``randomPoints`(n, bbox=[[0.0, 0.0, 0.0], [1.0, 1.0, 1.0]])

  Create n random points in a specified bbox.

`simple.``regularGrid`(x0, x1, nx, swapaxes=None)

  Create a regular grid of points between two points x0 and x1.

  Parameters:

  - x0: n-dimensional float (usually 1D, 2D or 3D).
  - x1: n-dimensional float with same dimension as x0.
  - nx: n-dimensional int with same dimension as x0 and x1. The space between x0 and x1 is subdivided in nx[i] equal parts along the axis i.
  - swapaxes: bool. If False(default), the points are number first in the direction of the 0 axis, then the next axis,… If True, numbering starts in the direction of the highest axis. This is the legacy behavior.

  Returns a rectangular grid of n-dimensional coordinates in an array with shape ( nx[0]+1, nx[1]+1, …, ndim ).

  Example:

      >>> regularGrid(0.,1.,4)
      array([[ 0.  ],
             [ 0.25],
             [ 0.5 ],
             [ 0.75],
             [ 1.  ]])
      >>> regularGrid((0.,0.),(1.,1.),(3,2))
      array([[[ 0.  , 0.  ],
              [ 0.33, 0.  ],
              [ 0.67, 0.  ]],
      <BLANKLINE>
             [[ 1.  , 0.  ],
              [ 0.  , 0.5 ],
              [ 0.33, 0.5 ]],
      <BLANKLINE>
             [[ 0.67, 0.5 ],
              [ 1.  , 0.5 ],
              [ 0.  , 1.  ]],
      <BLANKLINE>
             [[ 0.33, 1.  ],
              [ 0.67, 1.  ],
              [ 1.  , 1.  ]]])

`simple.``point`(x=0.0, y=0.0, z=0.0)

  Return a Formex which is a point, by default at the origin.

  Each of the coordinates can be specified and is zero by default.

`simple.``line`(p1=[0.0, 0.0, 0.0], p2=[1.0, 0.0, 0.0], n=1)

  Return a Formex which is a line between two specified points.

  p1: first point, p2: second point The line is split up in n segments.

`simple.``rect`(p1=[0.0, 0.0, 0.0], p2=[1.0, 0.0, 0.0], nx=1, ny=1)

  Return a Formex which is a the circumference of a rectangle.

  p1 and p2 are two opposite corner points of the rectangle. The edges of the rectangle are in planes parallel to the z-axis. There will always be two opposite edges that are parallel with the x-axis. The other two will only be parallel with the y-axis if both points have the same z-value, but in any case they will be parallel with the y-z plane.

  The edges parallel with the x-axis are divide in nx parts, the other ones in ny parts.

`simple.``rectangle`(nx=1, ny=1, b=None, h=None, bias=0.0, diag=None)

  Return a Formex representing a rectangular surface.

  The rectangle has a size(b,h) divided into (nx,ny) cells.

  The default b/h values are equal to nx/ny, resulting in a modular grid. The rectangle lies in the (x,y) plane, with one corner at [0,0,0]. By default, the elements are quads. By setting diag=’u’,’d’ of ‘x’, diagonals are added in /, resp. and both directions, to form triangles.

`simple.``Cube`()

  Create the surface of a cube

  Returns a TriSurface representing the surface of a unit cube. Each face of the cube is represented by two triangles.

`simple.``circle`(a1=2.0, a2=0.0, a3=360.0, r=None, n=None, c=None, eltype='line2')

  A polygonal approximation of a circle or arc.

  All points generated by this function lie on a circle with unit radius at the origin in the x-y-plane.

  - a1: the angle enclosed between the start and end points of each line segment (dash angle).
  - a2: the angle enclosed between the start points of two subsequent line segments (module angle). If `a2==0.0`, a2 will be taken equal to a1.
  - a3: the total angle enclosed between the first point of the first segment and the end point of the last segment (arc angle).

  All angles are given in degrees and are measured in the direction from x- to y-axis. The first point of the first segment is always on the x-axis.

  The default values produce a full circle (approximately). If $a3 < 360$, the result is an arc. Large values of a1 and a2 result in polygons. Thus circle(120.) is an equilateral triangle and circle(60.) is regular hexagon.

  Remark that the default a2 == a1 produces a continuous line, while a2 > a1 results in a dashed line.

  Three optional arguments can be added to scale and position the circle in 3D space:

  - r: the radius of the circle
  - n: the normal on the plane of the circle
  - c: the center of the circle

`simple.``polygon`(n)

  A regular polygon with n sides.

  Creates the circumference of a regular polygon with $n$ sides, inscribed in a circle with radius 1 and center at the origin. The first point lies on the axis 0. All points are in the (0,1) plane. The return value is a plex-2 Formex. This function is equivalent to circle(360./n).

`simple.``polygonSector`(n)

  Create one sector of a regular polygon with n sides

`simple.``triangle`()

  An equilateral triangle with base [0,1] on axis 0.

  Returns an equilateral triangle with side length 1. The first point is the origin, the second points is on the axis 0. The return value is a plex-3 Formex.

`simple.``quadraticCurve`(x=None, n=8)

  Create a collection of curves.

  x is a (3,3) shaped array of coordinates, specifying 3 points.

  Return an array with 2*n+1 points lying on the quadratic curve through the points x. Each of the intervals [x0,x1] and [x1,x2] will be divided in n segments.

`simple.``sphere`(ndiv=6, base='icosa', equiv='max')

  Create a triangulated approximation of a spherical surface.

  A (possibly high quality) approximation of a spherical surface is constructed as follows. First a simple base triangulated surface is created. Its triangular facets are subdivided by dividing all edges in ndiv parts. The resulting mesh is then projected on a sphere with unit radius. The higher ndiv is taken, the better the approximation. For ndiv=1, the base surface is returned.

  Parameters:

  - ndiv: number of divisions along the edges of the base surface.
  - base: the type of base surface. One of the following:
    - ‘icosa’: icosahedron (20 faces): this offers the highest quality with triangles of almost same size ans shape.
    - ‘octa’: octahedron (8 faces): this model will have the same mesh on each of the quadrants. The coordinate planes do not cut any triangle. This model is this fit to be subdivided along coordinate planes.

  Returns a TriSurface, representing a triangulated approximation of a spherical surface with radius 1 and center at the origin.

`simple.``sphere3`(nx, ny, r=1, bot=-90.0, top=90.0)

  Return a sphere consisting of surface triangles

  A sphere with radius r is modeled by the triangles formed by a regular grid of nx longitude circles, ny latitude circles and their diagonals.

  The two sets of triangles can be distinguished by their property number: 1: horizontal at the bottom, 2: horizontal at the top.

  The sphere caps can be cut off by specifying top and bottom latitude angles (measured in degrees from 0 at north pole to 180 at south pole.

`simple.``sphere2`(nx, ny, r=1, bot=-90, top=90)

  Return a sphere consisting of line elements.

  A sphere with radius r is modeled by a regular grid of nx longitude circles, ny latitude circles and their diagonals.

  The 3 sets of lines can be distinguished by their property number: 1: diagonals, 2: meridionals, 3: horizontals.

  The sphere caps can be cut off by specifying top and bottom latitude angles (measured in degrees from 0 at north pole to 180 at south pole.

`simple.``connectCurves`(curve1, curve2, n)

  Connect two curves to form a surface.

  curve1, curve2 are plex-2 Formices with the same number of elements. The two curves are connected by a surface of quadrilaterals, with n elements in the direction between the curves.

`simple.``sector`(r, t, nr, nt, h=0.0, diag=None)

  Constructs a Formex which is a sector of a circle/cone.

  A sector with radius r and angle t is modeled by dividing the radius in nr parts and the angle in nt parts and then creating straight line segments. If a nonzero value of h is given, a conical surface results with its top at the origin and the base circle of the cone at z=h. The default is for all points to be in the (x,y) plane.

  By default, a plex-4 Formex results. The central quads will collapse into triangles. If diag=’up’ or diag = ‘down’, all quads are divided by an up directed diagonal and a plex-3 Formex results.

`simple.``cylinder`(D, L, nt, nl, D1=None, angle=360.0, bias=0.0, diag=None)

  Create a cylindrical, conical or truncated conical surface.

  Returns a Formex representing (an approximation of) a cylindrical or (possibly truncated) conical surface with its axis along the z-axis. The resulting surface is actually a prism or pyramid, and only becomes a good approximation of a cylinder or cone for high values of nt.

  Parameters:

  - D: base diameter (at z=0) of the cylinder/cone,
  - L: length (along z-axis) of the cylinder/cone,
  - nt: number of elements along the circumference,
  - nl: number of elements along the length,
  - D1: diameter at the top (z=L) of the cylinder/cone: if unspecified, it is taken equal to D and a cylinder results. Setting either D1 or D to zero results in a cone, other values will create a truncated cone.
  - diag: by default, the elements are quads. Setting diag to ‘u’ or ‘d’ will put in an ‘up’ or ‘down’ diagonal to create triangles.

`simple.``boxes`(x)

  Create a set of cuboid boxes.

  x: Coords with shape (nelems,2,3), usually with x[:,0,:] < x[:,1,:]

  Returns a Formex with shape (nelems,8,3) and of type ‘hex8’, where each element is the cuboid box which has x[:,0,:] as its minimum coordinates and x[:,1,:] as the maximum ones. Note that the elements may be degenerate or reverted if the minimum coordinates are not smaller than the maximum ones.

  This function can be used to visualize the bboxes() of a geometry.

`simple.``boxes2d`(x)

  Create a set of rectangular boxes.

  Parameters:

  - x: Coords with shape (nelems,2,3), usually with x[:,0,:] < x[:,1,:] and x[:,:,2] == 0.

  Returns a Formex with shape (nelems,4,3) and of type ‘quad4’, where each element is the rectangular box which has x[:,0,:] as its minimum coordinates and x[:,1,:] as the maximum ones. Note that the elements may be degenerate or reverted if the minimum coordinates are not smaller than the maximum ones.

  This function is a 2D version of `bboxes()`.

`simple.``cuboid`(xmin=[0.0, 0.0, 0.0], xmax=[1.0, 1.0, 1.0], cs=None)

  Create a rectangular prism.

  Create a rectangular prism from two opposite corners. The vertices are specified in the global or a given coordinate system. The faces faces are parallel to the coordinate planes.

  Parameters:

  - xmin: float(3): minimum coordinates
  - xmax: float(3): maximum coordinates
  - cs: CoordSys: if specified, the cuboid is constructed in this coordinate system, and then transformed back to global axes.

  Returns a single element Formex with eltype ‘hex8’.

`simple.``cuboid2d`(xmin=[0.0, 0.0, 0.0], xmax=[1.0, 1.0, 0.0])

  Create a rectangle.

  Creates a rectangle with sides parallel to the global y-axis and global xz-plane, and having the points xmin and xmax as opposite corner points.

  Returns a single element Formex with eltype ‘quad4’.

`simple.``boundingBox`(obj, cs=None)

  Returns a cuboid that is the bounding box of some geometry

  The boundingBox is computed in the specified coordinate system. The default is the global axes.

  Returns a single hexahedral Formex object.