PK_ERROR_code_t         PK_BODY_create_solid_topology
(
--- received arguments ---
int                     n_topols,    --- number of topols
const PK_CLASS_t        classes[],   --- class of each topol
int                     n_relations, --- number of relations
const int               parents[],   --- parents
const int               children[],  --- children
const PK_TOPOL_sense_t  senses[],    --- sense in which child used by parent

--- returned arguments ---
PK_BODY_t        *const body,        --- created body
PK_TOPOL_t       *const topols,      --- created topols
PK_BODY_fault_t  *const fault,       --- fault indicator
int              *const fault_index  --- index of fault topol
)


This function creates the topology of a solid body.


Specific Errors:
    PK_ERROR_bad_class             bad class in classes array
    PK_ERROR_bad_value             a value in parents or children array
                                   is not a valid index to classes array


The array classes specifies the class of each topological entity.
Currently the only allowed values are:

    PK_CLASS_body
    PK_CLASS_shell
    PK_CLASS_face
    PK_CLASS_loop
    PK_CLASS_edge
    PK_CLASS_vertex

Each topological entity is referred to by its index in this array.

The arrays `parents, children and senses are all the same length which
is n_relations.
`parents[i]', `children[i]' and `senses[i]' define one relation between
two topological entities.  The values put into parents and children
are indices of the classes array.

It is optional whether a topological entity of class PK_CLASS_body appears
in the classes array.  If it does appear then it must be the first entry
and its relations with its children must all be defined.  If no
PK_CLASS_body appears in classes then the body's children are all the
topological entities which have no defined parent.  Such orphans may
currently only be shells, and if there is more than one, then the first
shell in classes must be the outer shell.

The following rules apply to the order of the relations:

 - the child relations to a common parent need not be contiguous.

 - when a body has more than one (shell) child defined then the outer shell
   must appear first.

 - edge children of a loop must appear in order around the loop.

 - vertex children of an edge must appear in the order of the direction of
   the edge.

senses indicate the manner in which a child is used by its parent.  This is
currently only meaningful for edge children where the sense should be set to:

    PK_TOPOL_sense_positive_c   the edge is in the same direction as its
                                parent loop

    PK_TOPOL_sense_negative_c   the edge is in the opposite direction to its
                                parent loop.

All other senses should be set to PK_TOPOL_sense_none_c.

The permitted classes and numbers of children and parents are as follows:

--------------------------------------------------------------------
Entity    Children      No. of children   Parents     No. of parents
--------------------------------------------------------------------
Body      Shells              >=1           -             -
Shell     Faces               >=1         Body            1
Face      Loops               >=0         Shell           1
Loop      Edges               >=1         Face            1
          or single vertex    1
Edge      Vertices            <=2         Loops           2
Vertex    None                0           Edges           >=1
                                          or single loop  1
--------------------------------------------------------------------

NB: - Each edge must be used twice as a child, once with each sense (this
      may be in the same loop).
    - A loop must have either a number of edges (with senses) as children,
      or a single vertex; it cannot have a mixture of edges and vertices, or
      more than one vertex.
    - A vertex must have a number of edges as parents, or a single loop; it
      cannot have both edges and loops, or more than one loop.

Success of the function is indicated by there being no PK error returned
and by fault being set to PK_BODY_fault_no_fault_c.

If the creation is successful:

 -  the created body is returned in body
 -  the entities corresponding to the entries in the classes array are
    returned in the topols array.  (Note that if a PK_CLASS_body appears
    in the classes array then the created body will appear in topols
    as well as in body.

If the creation is unsuccessful but no PK error is returned:

 -  no body is created
 -  a fault indicator is returned in fault
    (see documentation for PK_BODY_fault_t)
 -  the index (in the classes array) of the faulty item is returned if
    possible