HP OpenVMS Systems Documentation

Vector forms of many MTH$ routines are provided to support vectorized compiled applications. Vector versions of key F-floating, D-floating, and G-floating scalar routines employ vector hardware, while maintaining identical results with their scalar counterparts. Many of the scalar algorithms have been redesigned to ensure identical results and good performance for both the vector and scalar versions of each routine. All vectorized routines return bit-for-bit identical results as the scalar versions.

You can call the vector MTH$ routines directly if your program is written in VAX MACRO. If you are a Fortran programmer, specify the Fortran intrinsic function name only. The Fortran compiler will then determine whether the vector or scalar version of a routine should be used.

2.3.1 Exceptions

You should not attempt to recover from an MTH$ vector exception. After an MTH$ vector exception, the vector routines cannot continue execution, and nonexceptional values might not have been computed.

2.3.2 Underflow Detection

In general, if a vector instruction results in the detection of both a floating overflow and a floating underflow, only the overflow will be signaled.

Some scalar routines check to see if a user has enabled underflow detection. For each of those scalar routines, there are two corresponding vector routines: one that always enables underflow checking and one that never enables underflow checking. (In the latter case, underflows produce a result of zero.) The Fortran compiler always chooses the vector version that does not signal underflows, unless the user specifies the /CHECK=UNDERFLOW qualifier. This ensures that the check is performed but does not impair vector performance for those not interested in underflow detection.

2.3.3 Vector Routine Name Format

Use one of the formats in Table 2-3 to call (from VAX MACRO) a vector math routine that enables underflow signaling. (The E in the routine name means enabled underflow signaling.)

Use one of the formats in Table 2-4 to call (from VAX MACRO) a vector math routine that does not enable underflow signaling.

In the preceding formats, the following conventions are used:

You can call the vector MTH$ routines directly if your program is written in VAX MACRO.

In the following examples, keep in mind that vector real arguments are passed in V0, V1, and so on, and vector real results are returned in V0. On the other hand, vector complex arguments are passed in V0 and V1, V2, and V3, and so on. Vector complex results are returned in V0 and V1.

Example 1

The following example shows how to call the vector version of MTH$EXP. Assume that you do not want underflows to be signaled, and you need to use the current contents of all vector and scalar registers after the invocation. Before you can call the vector routine from VAX MACRO, perform the following steps.

1. Find EXP in the column of scalar names in Appendix B to determine:
   • The full vector routine name: MTH$VEXP_R3_V6
   • How the routine is invoked (CALL or JSB): JSB
   • The scalar registers that must be saved: R0 through R3 (as specified by R3 in MTH$VEXP_R3_V6)
   • The vector registers that must be saved: V0 through V6 (as specified by V6 in MTH$VEXP_R3_V6)
   • The vector registers used to hold the input arguments: V0
   • The vector registers used to hold the output arguments: V0
   • If there is a vector version that signals underflow (not needed in this example)
2. Save the scalar registers R0, R1, R2, and R3.
3. Save the vector registers V0, V1, V2, V3, V4, V5, and V6.
4. Save the vector mask register VMR.
5. Save the vector count register VCR.
6. Load the vector length register VLR.
7. Load the vector register V0 with the argument for MTH$EXP.
8. JSB to MTH$VEXP_R3_V6.
9. Store result in memory.
10. Restore all scalar and vector registers except for V0. (The results of the call to MTH$VEXP_R3_V6 are stored in V0.)

The following MACRO program fragment shows this example. Assume that:

• V0 through V6 and R0 through R3 have been saved.
• R4 points to a vector of 60 input values.
• R6 points to the location where the results of MTH$VEXP_R3_V6 will be stored.
• R5 contains the stride in bytes.

Note that MTH$VEXP_R3_V6 denotes an F-floating data type because there is no letter between V and E in the routine name. (For further explanation, refer to Section 2.3.3.) The stride (the number of array elements that are skipped) must be a multiple of 4 because each F-floating value requires 4 bytes.

MTVLR   #60                 ; Load VLR
MOVL    #4, R5              ; Stride
VLDL    (R4), R5, V0        ; Load V0 with the actual arguments
JSB     G^MTH$VEXP_R3_V6    ; JSB to MTH$VEXP
VSTL    V0, (R6), R5        ; Store the results

Example 2

The following example demonstrates how to call the vector version of OTS$POWDD with a vector base raised to a scalar power. Before you can call the vector routine from VAX MACRO, perform the following steps.

1. Find POWDD (V^S) in the column of scalar names in Appendix B to determine:
   • The full vector routine name: OTS$VPOWDD_R1_V8
   • How the routine is invoked (CALL or JSB): CALL
   • The scalar registers that must be saved: R0 through R1 (as specified by R1 in OTS$VPOWDD_R1_V8)
   • The vector registers that must be saved: V0 through V8 (as specified by V8 in OTS$VPOWDD_R1_V8)
   • The vector registers used to hold the input arguments: V0, R0
   • The vector registers used to hold the output arguments: V0
   • If there is a vector version that signals underflow (not needed in this example)
2. Save the scalar registers R0 and R1.
3. Save the vector registers V0, V1, V2, V3, V4, V5, V6, V7, and V8.
4. Save the vector mask register VMR.
5. Save the vector count register VCR.
6. Load the vector length register VLR.
7. Load the vector register V0 and the scalar register R0 with the arguments for OTS$POWDD.
8. Call OTS$VPOWDD_R1_V8.
9. Store result in memory.
10. Restore all scalar and vector registers except for V0. (The results of the call to OTS$VPOWDD_R1_V8 are stored in V0.)

The following MACRO program fragment shows how to call OTS$VPOWDD_R1_V8 to compute the result of raising 60 values to the power P. Assume that:

• V0 through V8 and R0 and R1 have been saved.
• R4 points to the vector of 60 input base values.
• R0 and R1 contain the D-floating value P.
• R6 points to the location where the results will be stored.
• R5 contains the stride.

Note that OTS$VPOWDD_R1_V8 raises a D-floating base to a D-floating power, which you determine from the DD in the routine name. (For further explanation, refer to Section 2.3.3.) The stride (the number of array elements that are skipped) must be a multiple of 8 because each D-floating value requires 8 bytes.

                              ; R0/R1 already contains the power
MTVLR   #60                   ; Load VLR
MOVL    #8, R5                ; Stride
VLDQ    (R4), R5, V0          ; Load V0 with the actual arguments
CALLS   #0,G^OTS$VPOWDD_R1_V8 ; CALL OTS$VPOWDD
VSTQ    V0, (R6), R5          ; Store the results

This section describes the fast-vector math routines that offer significantly higher performance at the cost of slightly reduced accuracy when compared with corresponding standard vector math routines. Also note that some fast-vector math routines have restricted argument domains.

When you specify the compile command qualifiers /VECTOR and /MATH_LIBRARY=FAST, the Compaq Fortran compiler selects the appropriate fast-vector math routine, if one exists. The default is /MATH_LIBRARY=ACCURATE. You must specify the /G_FLOATING compile qualifier in conjunction with the /MATH_LIBRARY=FAST and /VECTOR qualifiers to access the G_floating routines.

You can call these routines from VAX MACRO using the standard calling method. The math function names, together with corresponding entry points of the fast-vector math routines, are listed in Table 2-5.

2.4.1 Exception Handling

%SYSTEM-F-VARITH, vector arithmetic fault

2.4.2 Special Restrictions On Input Arguments

The special restrictions listed in Table 2-6 apply only to fast-vector routines SIN, COS, and TAN. The standard vector routines handle the full range of VAX floating-point numbers.

If the application program uses arguments outside of the listed domain, the routine returns the following error message:

%SYSTEM-F-VARITH, vector arithmetic fault

If the application requires argument values beyond the listed limits, use the corresponding standard vector math routine.

2.4.3 Accuracy

The fast-vector math routines do not guarantee the same results as those obtained with the corresponding standard vector math routines. Calls to the fast-vector routines generally yield results that are different from the scalar and original vector MTH$ library routines. The typical maximum error is a 2-LSB (Least Significant Bit) error for the F_floating routines and a 4-LSB error for the D_floating and G_floating routines. This generally corresponds to a difference in the 6th significant decimal digit for the F_floating routines, the 15th digit for D_floating, and the 14th digit for G_floating.

2.4.4 Performance

The fast-vector math routines generally provide performance improvements over the standard vector routines ranging from 15 to 300 percent, depending on the routines called and input arguments to the routines. The overall performance improvement using fast-vector math routines in a typical user application will increase, but not at the same level as the routines themselves. You should do performance and correctness testing of your application using both the fast-vector and the standard vector math routines before deciding which to use for your application.