PK_BODY_create_solid_topology

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.

NOTE: This function is deprecated and has been superseded by
PK_BODY_create_topology_2.



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'. As it has no geometry attached
    it will not pass the checker.
 -  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