SURSUB
SURSUB is an evaluation subroutine that computes surface coordinates and their derivatives for a SURFACE element (C++). The use of SURSUB is optional; it is not required when a Parasolid file is provided as input for the surface definition.
Note: | Use mixed case names for the Adams subroutine names when using the C style interface. For the default subroutine name capitalize the first letter and have the remaining letters lower case; Sursub for example. Doing this ensures that Adams Solver correctly distinguishes a C style subroutine from Fortran and calls with the appropriate interface. |
Use
Corresponding Statement
Calling Sequence
For FORTRAN use:
SUBROUTINE SURSUB (ID, PAR, NPAR, U, V, IORD, IFLAG, VALUES, IERR)For C++ use:
SURSUB (int ID, double* PAR, int NPAR, double U, double V, int IORD, int IFLAG, double* VALUES, int* IERR)
Input Arguments
id | An integer variable that provides the identifier of the SURFACE statement that is being defined by SURSUB. |
iflag | An integer variable that Adams Solver sets to indicate why the routine is being called:  When iflag is 0 Adams Solver calling to compute the value of the user-written variable. When iflag is set to 1 or 3 do any initializations that your subroutine requires. When your user-defined subroutine has static data that needs to be saved and restored to support the Adams Solver commands Save and Reload, then call the serialization functions for your data when iflag is set to 7, and the un-serialization functions when iflag is set to 9. Note: In simple subroutines where serializing data is not needed, you can declare iflag as a logical variable. In this case you can do any initializations when Adams Solver sets iflag to true, and compute the subroutine's value when Adams Solver sets iflag to false. |
iord | An integer variable that specifies the order of the derivative that SURSUB returns. The possible values are: zero - Return surface coordinates. one - Return first derivatives with respect to u, v. two - Return second derivatices with respect to u, v. |
npar | An integer variable that indicates the number of constants specified in the USER parenthetical list. The purpose of npar is to provide SURSUB with the number of values stored in the par array. |
par | A double-precision array of constants that is taken in order from the USER parenthetical list of the SURFACE statement. |
u | A double-precision variable that specifies the value of the independent parameter u, which SURSUB uses to evaluate coordinates of a point on the surface. Adams Solver restricts u to be: Greater than or equal to the MINPAR[1] value on the SURFACE statement (-1.0 by default). Less than or equal to the MAXPAR[1] value on the SURFACE statement (1.0 by default). |
v | A double-precision variable that specifies the value of the independent parameter v which SURSUB uses to evaluate coordinates of a point on the surface. Adams Solver restricts v to be: Greater than or equal to the MINPAR[2] value on the SURFACE statement (-1.0 by default). Less than or equal to the MAXPAR[2] value on the SURFACE statement (1.0 by default). |
Output Arguments
values | A double-precision array that contains the output data. The data are dependent on IORD and IERR. This is elaborated below. Note: All data are to be returned, column ordered, in a single array. | |||
IORD=0, IERR=0 | IORD=0, IERR=1 | IORD=1, IERR=0 or IERR=1 | IORD=2 IERR=0 or IERR=1 | |
 |  |  |  | |
3x1 array | 5x1 array | 3x2 array | 3x3 array | |
IERR | An integer variable that specifies whether or not the [u,v] provided as input is on the surface. IERR=0 implies the point is on the SURFACE IERR=1 implies the point is not on the SURFACE IERR should be set only when IORD=0. IF IERR=0, then SURSUB should just return the x ,y ,z coordinates of the point on the SURFACE. The first three components of the output array VALUES should contain this data. The last two components of VALUES can remain undefined. IF IERR=1, then SURSUB is required to extrapolate the SURFACE definition and return the x, y, z coordinates of the point on the extrapolated SURFACE. The first three components of the output array VALUES should contain this data. In addition, SURSUB is also expected to return the u,v values of the point on the surface closest to the x, y, z coordinates that were calculated. These values, u* and v*, are returned in components 4,5 of the output array VALUES. | |||
Extended Definition
SURSUB is a user-written subroutine that allows you to define a SURFACE. The x, y, and z coordinates of a point on a parametric surface are functions of independent parameters, (u,v). As (u,v) vary from their minimum to maximum values, the functions x(u,v), y(u,v), and z(u,v) sweep out points on the surface.
A surface can be open or closed in both u and v. A surface closed in u (UCLOSED) meets along the edges defined by the maximum and minimum values of u. A surface closed in v (VCLOSED) meets along the edges defined by the maximum and minimum values of v.
Surfaces can be used in Adams constraints. A surface marker allowed to only move on the surface is provided for this purpose. Any valid constraint (joint, jprim, and so on) can be constructed using the surface marker.
A surface has parameterization limits as prescribed by MINPAR and MAXPAR. It is likely, however, that there are regions within the parameter space where the surface is not defined. The finiteness of the surface (including holes) are modeled using a penalty approach. The penalty approach applies a force to prevent the surface marker from moving off the edge of an open surface, or from moving into a hole in the surface. This approach necessarily requires that the surface marker move off the surface for a short duration. In such a situation, the surface descriptor is provided with [u,v] values outside the domain of the surface. The descriptor is expected to extrapolate the surface definition to provide an estimated location of the surface marker at these [u,v] points. Linear extrapolation is adequate for most purposes.
Adams Solver automatically extrapolates the surface as needed when the surface description is provided as a Parasolid geometry file. You are required to perform such extrapolation when you provide the surface definition through a SURSUB user-written subroutine.
If [u,v] are the parameters corresponding to the current point on the surface, and [u*, v*] are the parameters for the closest material point on the surface to [u,v], the penalty force that is applied in the [u,v] domain is:
F = -K * [(u-u*)2 + (v-v*)2]
K = 108
K = 108
At this time, you have no control over the stiffness parameter, K.
Caution: | Define the SURFACE only as a function of u, v. Do not make calls to the SYSARY and SYSFNC utility subroutines to access other system variables. |
FORTRAN - Prototype
A sample structure for SURSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE SURSUB ( ID, PAR, NPAR, U, V, IORD, IFLAG,
& VALUES, IERR )
C
C Inputs:
C
INTEGER ID
DOUBLE PRECISION PAR( * )
INTEGER NPAR
DOUBLE PRECISION U,V
INTEGER IORD
INTEGER IFLAG
C
C Outputs:
C
DOUBLE PRECISION VALUES( * )
INTEGER IERR
C
C+---------------------------------------------------------------*
C
C ID
Identifier of calling CURVE statement
C PAR Array containing passed parameters
C NPAR Number of passed parameters
C U,V Curve parameter value
C IORD Derivative order of value to be returned
C IFLAG Initialization pass flag
C VALUES Derivative values of CURVE returned to ADAMS
C IERR Return flag; 0 =(U,V) on surface
1 =(U,V) outside surface
C
C+---------------------------------------------------------------*
C
C Local Variables:
C
...
C
C External Functions:(Note : This function must be written by you)
C
EXTERNAL UV_IS_OUTSIDE_SURFACE
LOGICAL UV_IS_OUTSIDE_SURFACE
C
C+---------------------------------------------------------------*
C
IF ( IFLAG ) THEN
C
C
Initialization call:
C
...
<perform initialization operations>
<opening files, calculating constants etc.>
...
RETURN
ENDIF
C
C
Computation call:
C
IERR = 0
IF ( IORD .EQ. 0 ) THEN
C
C
Check whether [u,v] lie on the surface:
C
IF ( UV_IS_OUTSIDE_SURFACE(...) ) THEN
...
<extrapolate surface>
<calculate x-y-z-coordinates corresponding to [u,v]
<calculate [u*,v*] on surface, closest to [u,v]>
...
C
C
Set IERR, and VALUES:
C
IERR = 1
VALUES(1) = x....
VALUES(2) = y....
VALUES(3) = z....
VALUES(4) = u*...
VALUES(5) = v*...
ELSE
...
<calculate x-y-z-coordinates corresponding to [u,v]
<calculate [u*,v*] on surface, closes to [u,v>]
...
C
C
Set IERR, and VALUES:
C
VALUES(1) = x...
VALUES(2) = y...
VALUES(3) = z...
ENDIF
ELSEIF ( IORD .EQ. 1 ) THEN
C
C
Need matrix of 1st partial derivatives wrt. Parameters u,v:
C
...
<calculate partials of x-y-z-coordinates wrt to [u,v]>
...
C
C
Return the 3x2 matrix of partials, sorted by column
C
VALUES(1) = dx_du... VALUES(2) = dy_du...
VALUES(3) = dz_du... VALUES(4) = dx_dv...
VALUES(5) = dy_dv... VALUES(6) = dz_dv...
ELSEIF ( IORD .EQ. 2 ) THEN
C
C
Need matrix of 2nd partial derivatives wrt. Parameters u,v:
C
...
<calculate 2nd partials of x-y-z-coordinates wrt to [u,v]>
...
C
C
Return the 3x3 matrix of partials, sorted by column
C
VALUES(1) = d2x_dudu...
VALUES(2) = d2y_dudu...
VALUES(3) = d2z_dudu...
VALUES(4) = d2x_dudv...
VALUES(5) = d2y_dudv...
VALUES(6) = d2z_dudv...
VALUES(7) = d2x_dvdv...
VALUES(8) = d2y_dvdv...
VALUES(9) = d2z_dvdv...
ELSECC
Error - Should not be here:
C
CALL ERMESS (...)
ENDIF
C
RETURN
END
& VALUES, IERR )
C
C Inputs:
C
INTEGER ID
DOUBLE PRECISION PAR( * )
INTEGER NPAR
DOUBLE PRECISION U,V
INTEGER IORD
INTEGER IFLAG
C
C Outputs:
C
DOUBLE PRECISION VALUES( * )
INTEGER IERR
C
C+---------------------------------------------------------------*
C
C ID
Identifier of calling CURVE statement
C PAR Array containing passed parameters
C NPAR Number of passed parameters
C U,V Curve parameter value
C IORD Derivative order of value to be returned
C IFLAG Initialization pass flag
C VALUES Derivative values of CURVE returned to ADAMS
C IERR Return flag; 0 =(U,V) on surface
1 =(U,V) outside surface
C
C+---------------------------------------------------------------*
C
C Local Variables:
C
...
C
C External Functions:(Note : This function must be written by you)
C
EXTERNAL UV_IS_OUTSIDE_SURFACE
LOGICAL UV_IS_OUTSIDE_SURFACE
C
C+---------------------------------------------------------------*
C
IF ( IFLAG ) THEN
C
C
Initialization call:
C
...
<perform initialization operations>
<opening files, calculating constants etc.>
...
RETURN
ENDIF
C
C
Computation call:
C
IERR = 0
IF ( IORD .EQ. 0 ) THEN
C
C
Check whether [u,v] lie on the surface:
C
IF ( UV_IS_OUTSIDE_SURFACE(...) ) THEN
...
<extrapolate surface>
<calculate x-y-z-coordinates corresponding to [u,v]
<calculate [u*,v*] on surface, closest to [u,v]>
...
C
C
Set IERR, and VALUES:
C
IERR = 1
VALUES(1) = x....
VALUES(2) = y....
VALUES(3) = z....
VALUES(4) = u*...
VALUES(5) = v*...
ELSE
...
<calculate x-y-z-coordinates corresponding to [u,v]
<calculate [u*,v*] on surface, closes to [u,v>]
...
C
C
Set IERR, and VALUES:
C
VALUES(1) = x...
VALUES(2) = y...
VALUES(3) = z...
ENDIF
ELSEIF ( IORD .EQ. 1 ) THEN
C
C
Need matrix of 1st partial derivatives wrt. Parameters u,v:
C
...
<calculate partials of x-y-z-coordinates wrt to [u,v]>
...
C
C
Return the 3x2 matrix of partials, sorted by column
C
VALUES(1) = dx_du... VALUES(2) = dy_du...
VALUES(3) = dz_du... VALUES(4) = dx_dv...
VALUES(5) = dy_dv... VALUES(6) = dz_dv...
ELSEIF ( IORD .EQ. 2 ) THEN
C
C
Need matrix of 2nd partial derivatives wrt. Parameters u,v:
C
...
<calculate 2nd partials of x-y-z-coordinates wrt to [u,v]>
...
C
C
Return the 3x3 matrix of partials, sorted by column
C
VALUES(1) = d2x_dudu...
VALUES(2) = d2y_dudu...
VALUES(3) = d2z_dudu...
VALUES(4) = d2x_dudv...
VALUES(5) = d2y_dudv...
VALUES(6) = d2z_dudv...
VALUES(7) = d2x_dvdv...
VALUES(8) = d2y_dvdv...
VALUES(9) = d2z_dvdv...
ELSECC
Error - Should not be here:
C
CALL ERMESS (...)
ENDIF
C
RETURN
END
C Style Prototype
typedef void adams_c_SURSUB(const struct sAdamsSurface* srf, double ALPHA, double BETA, int IORD, int IFLAG, double* VALUES, int* IERR );
/*
* SURFACE
*/
struct sAdamsSurface
{
int ID;
int NPAR;
const double* PAR;
/* const char* FILENAME; */
int ORDER[2];
int CLOSED[2];
double MINPAR[2];
double MAXPAR[2];
};
Examples
The figure below illustrates a circular surface S with a hole H at its very center. The surface S belongs to a body A. A point P, belonging to a different body B, is required to move on the surface S. The bounds of the parameterization are the outer perimeter of the circular suface A circular surface with a hole in its center.
A circular surface with a hole in its center.
For an example of this subroutine, see sursub.c.