Utilities

PCL Reference Manual > Finite Element Functions > Utilities

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''">

Utilities

This section is used to describe a variety of finite element model utility functions


fem_geom_match_closest	(source_select, target_select, entity_count, match, distance, length)


Description:
This function will compare two lists of entities, returning the entities from the second list that have the smallest geometric distances to entities in the first list.
Input:
STRING	source_select[]	This value specifies a selection of geometric and finite element entities. Each entity in this list will be compared against all of the entities in the input value target_select.
STRING	target_select[]	This value specifies a selection of geometric and finite element entities. All of the entities in this list will be compared against each entity listed in the input value source_select.
Output:
INTEGER	entity_count	This value will return the number of entities in the returned values match and distance.
STRING	match[VIRTUAL]	This value will return a description of the matched entities from the input value target_select.
REAL	distance(VIRTUAL)	This value will return the centroid to centroid distance of each entity listed in the output value match to each entity listed in the input value source_select.
INTEGER	length	This value returns the length of the output value match.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

This function computes all distances based on the centroid of the entities in the input lists. Assumptions are made for geometric entities that will cause the distance calculations for degenerate shapes to be inaccurate.

This function can make use of finite element model sub-entities but only 2D element edges and 3D element sub-entities will be accepted.

This function will not return accurate results if cubic elements are used as input.

Space is internally allocated for the string returned by the output values match and distance. It is the responsibility of the calling function to free the allocated string storage space.

Example:

Please see fem_geom_match_closest.


fem_geom_edge_length	(element_select, lengths, entity_count)


Description:
This function determines the length of finite element model bar elements and 2D geometric element edges.
Input:
STRING	element_select[]	This value specifies a selection of finite element model bar elements and 2D geometric element edges.
Output:
REAL	lengths(VIRTUAL)	This value returns the length of each entity in the input value element_select.
INTEGER	entity_count	This value returns the number of entities in the input value element_select and the number of offsets in the output value lengths.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

This function will not return accurate results if cubic elements are used as input.

Space is internally allocated for the string returned by the output value lengths. It is the responsibility of the calling function to free the allocated string storage space.

Example:

Please see fem_geom_edge_length.


fem_geom_edge_length2	(edge_count, element_id, element_face_id, element_face_edge_id, segment_count, edge_length)


Description:
This function finds the length of the edge of elements.
Input:
INTEGER	edge_count	This value specifies the number of edges in the element_id array.
INTEGER	element_id(edge_count)	This array specifies the element ids.
INTEGER	element_face_id(edge_count)	This array specifies the element face ids. This value can be 0, or 1 to 6. Values between 1 and 6 are used to identify the element’s face number. When this value is equal to 0 the input value element_face_edge_id will designate the unique edge number.
INTEGER	element_face_edge_id(edge_count)
		This array specifies the element face edge id. If the input value element_face_id is greater than 0, this value will designate the face’s edge number for the element face with a value ranging from 1 to 4. If the input value element_face_id is equal to 0, this value will designate the unique edge number of the element with a value that ranging from 1 to 12.
INTEGER	segment_count	This value specifies the number of segments by which an element edge length will be divided. If this value is 0, it will be assumed that the edge of the element will be comprised of a single segment formed by a straight line between the nodes making up the corners of the edge of the element.
Output:
REAL	edge_length(VIRTUAL)	This array returns the lengths of the element edges. The number of offsets in the array will be set by the input value edge_count.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate an error.
Error Conditions:
-1	This is an internal error status condition. There is no corresponding status message in the message database.

Remarks:

Memory is allocated for the output variable within this function. If memory was allocated prior to the call, it is released prior to re-allocation. Therefore, if this function is used within a loop, there is no need to release the memory of the output variable.

Example:

Please see fem_geom_edge_length2.


fem_geom_face_area	(element_select, areas, entity_count)


Description:
This function determines the face area of finite element model shell elements and 3D geometric element edges.
Input:
STRING	element_select[]	This value specifies a selection of finite element model shell elements and 3D geometric element edges.
Output:
REAL	areas(VIRTUAL)	This value returns the face area of each entity in the input value element_select.
INTEGER	entity_count	This value returns the number of entities in the input value element_select and the number of offsets in the output value areas.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

This function will not return accurate results if cubic elements are used as input.

Space is internally allocated for the string returned by the output value areas. It is the responsibility of the calling function to free the allocated string storage space.

Example:

Please see fem_geom_face_area.


fem_geom_elem_volume	(element_select, volumes, entity_count)


Description:
This function determines the volume of finite element model and 3D geometric elements.
Input:
STRING	element_select[]	This value specifies a selection of finite element model and 3D geometric elements.
Output:
REAL	volumes(VIRTUAL)	This value returns the volume of each entity in the input value element_select.
INTEGER	entity_count	This value returns the number of entities in the input value element_select and the number of offsets in the output value volumes.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

This function will not return accurate results if cubic elements are used as input.

Space is internally allocated for the string returned by the output value volumes. It is the responsibility of the calling function to free the allocated string storage space.

Example:

Please see fem_geom_elem_volume.


fem_geom_elem_location	(element_select, locations, entity_count)


Description:
This function will find the location of the centroid of finite element model and geometric elements, element faces, and element edges. Note that the “centroid” locations does not correspond to the center of gravity for the supplied finite element entities, but instead, to their parametric centers which are then mapped into real space.
Input:
STRING	element_select[]	This value specifies a selection of finite element model elements, element faces, and element edges.
Output:
REAL	locations(VIRTUAL)	This value returns a two dimensional array specifying the centroidal locations of each entity in the input value element_select. See the remarks below for more information.
INTEGER	entity_count	This value returns the number of entities in the input value element_select and the number of offsets in the first dimension of the two dimensional output value locations.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

This function will not accept 3D element edges.

This function will not return accurate results if cubic elements are used as input.

The output value locations will returns a two dimensional array where the first dimension is the number of entities in the input value element_select and the second dimension is three. Each offset can be interpreted in the following manner:


	Variable Notation	Description

	location(1,1)	This is the X axis location of the centroid for the first element listed in the input value element_select.
	location(1,2)	This is the Y axis location of the centroid for the first element listed in the input value element_select.
	location(1,3)	This is the Z axis location of the centroid for the first element listed in the input value element_select.
	.
	.
	.
	location(entity_count,1)	This is the X axis location of the centroid for the last element listed in the input value element_select.
	location(entity_count,2)	This is the Y axis location of the centroid for the last element listed in the input value element_select.
	location(entity_count,3)	This is the Z axis location of the centroid for the last element listed in the input value element_select.

Space is internally allocated for the string returned by the output value locations. It is the responsibility of the calling function to free the allocated string storage space.

Example:

Please see fem_geom_elem_location.


fem_get_mesh_edge_def_data	(curve_id, mesh_status, mesh_type, num_elements, mesh_ratio, num_hard, node_locations)


Description:
This function returns information about the definition of a mesh and/or a mesh seed on a curve or on an edge of a surface or solid.
Input:
INTEGER	curve_id	This value specifies the internal database identifier value for a curve or an edge of a surface or solid.
Output:
INTEGER	mesh_status	This value returns information stating whether the curve or edge has a finite element mesh, a mesh seed, both a mesh and a mesh seed, or no mesh or mesh seed defined along its length. See the remarks below for more information.
INTEGER	mesh_type	This value returns information about how the mesh or mesh seed on the curve or edge is defined. See the remarks below for more information.
INTEGER	num_elements	This value returns the number of finite element model elements on the curve or edge specified by the input value curve_id and the number of offsets in the output value node_locations.
REAL	mesh_ratio	This value returns the mesh ratio for the finite element model mesh defined on the curve or edged specified by the input value curve_id.
INTEGER	num_hard	This value returns the number of points in each node location.
REAL	node_locations [VIRTUAL]
		This value returns the curve normalized arc length locations of the nodes along the specified curve or edge. The number of offsets defined for this array will be returned by the output value num_elements.
INTEGER	<Return Value>	This function returns a value of 0 when executed successfully and a non zero value to indicate a change in status or an error.
Error Conditions:
None.

Remarks:

The output value mesh_status can return the following values:


	Value	Description

	0	No meshes or mesh seeds where found.
	1	Mesh seeds only where found.
	2	Meshes only where found.
	3	Both meshes and mesh seeds where found.

The output value mesh_type can return the following values:


	Value	Description

	1	The finite element mesh is uniform.
	2	The finite element mesh has a one way bias.
	3	The finite element mesh has a two way bias.
	4	The finite element mesh is defined by an arc length table.

Space is internally allocated for the string returned by the output value node_locations. It is the responsibility of the calling function to free the allocated string storage space.

Example:

Please see fem_get_mesh_edge_def_data.