Adams Basic Package > Adams Solver > Welcome to Adams Solver Subroutines > User-Written Subroutines > CURSUB

CURSUB

CURSUB is an evaluation subroutine that computes curve coordinates and their derivatives for a CURVE statement (C++ or FORTRAN). CURSUB is optional. You can use it to define a curve instead of using control points or data points.
 
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; Cursub 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

SUBROUTINE CURSUB (id, par, npar, alpha, iord, iflag, values)

Input Arguments

 
alpha
A double-precision variable that specifies the value of the independent parameter a which CURSUB uses to evaluate a curve. Adams Solver restricts a to be:
Greater than or equal to the MINPAR value on the CURVE statement (-1.0 by default).
Less than or equal to the MAXPAR value on the CURVE statement (1.0 by default).
id
An integer variable that provides the identifier of the CURVE statement, which requests information from the CURSUB. Adams Solver automatically derives additional information (such as the par argument) from the identifier of the corresponding statement.
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 CURSUB returns. The possible values are:
zero (return curve coordinates)
one (return first derivatives with respect to alpha)
two (return second derivatives with respect to alpha).
npar
An integer variable that indicates the number of constants specified in the USER parenthetical list. The primary purpose of npar is to provide the CURSUB evaluation subroutine 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 CURVE statement.

Output Arguments

 
values
A double-precision array of size three that returns the x, y, and z coordinates of the curve or their first or second derivatives with respect to a. The values the CURSUB should compute and return depend on the input value of argument iord, as summarized next:
iord:
values (1):
values (2):
values (3):
0
1
2

Extended Definition

The CURVE statement lets you define a uniform B-Spline curve using control points or a tensioned B-Spline curve that is fitted to data points. If you cannot represent the curve you want using a uniform or tensioned B-Spline, you can use the FUNCTION=USER ( ) argument in the CURVE statement and write a CURSUB evaluation subroutine to calculate the curve coordinates and derivatives.
 
Caution:  
Define the curve only as a function of α. Don't make calls to the SYSARY and SYSFNC utility subroutines to access other system variables.

FORTRAN - Prototype

A sample structure for CURSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE CURSUB ( ID, PAR, NPAR, ALPHA, IORD,
&                    IFLAG, VALUES )
C
C === Type and dimension statements ===================
C
C - External variable definitions ---------
C
INTEGER                     ID
DOUBLE PRECISION            PAR( * )
INTEGER                     NPAR
DOUBLE PRECISION            ALPHA
INTEGER                     IORD
INTEGER                     IFLAG
DOUBLE PRECISION            VALUES( 3 )
C
C ID       Identifier of calling CURVE statement
C PAR      Array containing passed parameters
C NPAR     Number of passed parameters
C ALPHA    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
C - Local variable and parameter definitions ----
C
...
C
C === Executable code =================================
C
C Assign parameters to readable variable names
C...CIF ( IFLAG ) THEN
C
C - Subroutine initialization -----------
C
...
C
ENDIF
C
C - Compute and assign the curve coordinates ----
C
IF ( IORD .EQ. 0 ) THEN
C
C Your algorithm
C
...
C
C Assign values for the X, Y, and Z coordinates
C
VALUES(1) = ...
VALUES(2) = ...
VALUES(3) = ...
C
C - Compute and assign the curve first derivatives -
C
ELSE IF ( IORD .EQ. 1 ) THEN
C
C Your algorithm
C
...
C
C Assign values for the X, Y, and Z first derivatives
C
VALUES(1) = ...
VALUES(2) = ...
VALUES(3) = ...
C
C - Compute and assign the curve second derivatives -
C
ELSE
C
C Your algorithm
C
...
C
C Assign values for the X, Y, and Z second derivatives
C
VALUES(1) = ...
VALUES(2) = ...
VALUES(3) = ...
C
ENDIF
C
RETURN
END

C Style - Prototype

typedef void adams_c_CURSUB(const struct sAdamsCurve* crv, double ALPHA, int IORD, int IFLAG, double* VALUES );
/*
* CURVE
*/
struct sAdamsCurve
{
int ID;
int NPAR;
const double* PAR;
int CLOSED;
int ORDER;
double MINPAR;
double MAXPAR;
};
 

Examples

For an example of this subroutine, see cursub.f