External Responses

The DRESP3 bulk data entry, in combination with the LOADLIB I/O option entry, allows for the definition of responses through user-defined external functions. The external functions may be written in either Fortran or C. The resulting libraries should be accessible by OptiStruct regardless of the coding language, providing that consistent function prototyping is respected, and adequate compiling and linking options are used.

Writing External Functions

The OptiStruct installation provides "barebone" functions for Fortran (dresp3_barebone.F) and for C (dresp3_barebone.c) with proper function definition, arguments, and compilation directives. These files can be used as starting points to write your own functions.

Fortran functions are defined as follows:

integer function myfunct(iparam, rparam, nparam,

iresp, rresp, nresp,  

userdata) 

character*32000 userdata

integer nparam, nresp

integer iparam(nparam), iresp(nresp)

double precision param(nparam), rresp(nresp)

C functions are defined as follows :

int myfunct(int* iparam, double* rparam, int* nparam,

int* iresp, double* rresp, int* nresp, 

char* userdata) 

Note that the functions' arguments are identical in both languages so as to preserve compatibility. However, since Fortran always passes arguments by address, it is important to understand that external C functions receive pointers instead of variables.

In order to ensure portability, the following must be adhered to:

·      Function names should be written using either all lower-case or all upper-case characters.

·      Only alphanumeric characters should be used.

·      Underscore characters are prohibited.

·      Names cannot be longer than eight characters.

Function return values

External functions should return 0 or 1 for successful completion, where 1 indicates that a user-defined information message should be output by OptiStruct. External functions should return -1 in case of fatal error, in which case OptiStruct will terminate after outputting a user-defined error message. See below for more information about error and information messages.

Function arguments

The following table briefly describes the arguments which are passed from OptiStruct to the external functions.

Parameters:

·     nparam is the number of input parameters that were defined on the DRESP3 card.

·     rparam(nparam) contains the values of the input parameters as evaluated by OptiStruct.

·     iparam(nparam) indicates the types of the input parameters as described below.

Parameter values are passed in the exact order in which they were defined on the DRESP3 card, regardless of their type. Using the parameter types table is optional, for instance to perform verifications or code-branching.

 The following types are currently supported:

Responses:

·      nresp is the maximum number of responses which the function is able to compute, as defined on the MAXRESP field of the DRESP3 card.

·      rresp(nresp) returns the values of the responses as evaluated by the external function.

·      iresp(nresp) contains the responses requests as described below.

The responses requests table indicates which of the available responses are actually needed by OptiStruct. Entries in iresp(nresp) are flagged as 1 for requested responses and as 0 otherwise. Using that information is optional, and allows for saving computational effort by not evaluating responses which OptiStruct does not need.

Userdata string

Upon entering the function, the userdata string contains data as defined in the USRDATA field of the DRESP3 card. It provides a convenient mechanism to pass constants or any other relevant information to the function. There are no restrictions regarding the contents of the string, but its length must be 32000 characters at most.

Upon exiting the function, the string may contain a user-defined error or information message. The updated string is then returned to OptiStruct, where it is printed to the standard output (.out file and/or screen). Here again, the contents of the string are not restricted as long as its length does not exceed 32000 characters.

The error or information messages may be formatted by using the character "|" as a line-break indicator. Standard C escape sequences are supported as well. It is advised, but not necessary, to format messages in such a way that each line does not exceed 80 characters, since the same convention is used in OptiStruct's output files.

Building External Libraries

Windows systems with Microsoft Developer Studio

Creating dynamic libraries under Windows with Microsoft Developer Studio is an extremely easy task. Simply start a new project and select either "Fortran Dynamic Link Library" for Fortran, or "Win32 Dynamic-Link Library" for C.

For Fortran libraries, you need to change the argument passing conventions in the project settings. Under the "Fortran" tab, select the category "External Procedures" and then change the "Argument Passing Conventions" to "C, By Reference".

UNIX systems

Under UNIX, the general syntax to build a shared library starting from a Fortran or C file is:

where FC refers to the Fortran compiler (for instance f77), CC refers to the C compiler (for instance cc or gcc), and LD refers to the linker (for instance ld) installed on your computer. Please refer to your system's manuals for more information.

The compiler and linker options provide information about the platform you are building the library for. For instance, they may indicate whether the library should be built in 64 bits or 32 bits mode. The linker options also specify that you are building a shared library. Other options, such as code optimization parameters, are left to your discretion and should not usually affect the compatibility with OptiStruct.

The following table defines options for each of OptiStruct's release platforms, which have been verified to work correctly on various systems. Keep in mind that these options might change depending on the compilers and linker installed on your computer, so please refer to your operating system manual for further information.

Once your library has been built, you can verify that the functions have been exported correctly by using nm mylib.so on UNIX systems and dumpbin /exports mylib.dll on Windows systems with Microsoft Developer Studio. This command will display the list of symbols found in the library, among which you should recognize the function(s) which you have written.

Note that some Fortran compilers convert function names to lower-case or upper-case symbols, and some compilers also append an underscore to these names. However, in your input decks, you do not have to worry about the exact symbol name. Simply use the function name as it is defined in your code, and OptiStruct will automatically locate the appropriate symbol.

Using External Libraries

All files referenced here are located in the HyperWorks installation directory under <install_directory>/demos/os/manual/.

To locate the HyperWorks installation directory, <install_directory>, use the following approach:

From the permanent menu, select the global panel and review the path next to template file:. <install_directory> is the portion of the path preceding the templates/ directory on PC, and the hm/ directory on UNIX.

If you need more help finding the installation directory, see Finding the installation directory <install_directory> or contact your systems administrator.

Simple example

The files dresp3_simple.F and dresp3_simple.c contain source code for simple examples of external functions written in Fortran and C, respectively. Both functions are named mysum and compute two responses – the sum of the parameters and the averaged sum of the parameters.

The input deck dresp3_simple.fem contains an example problem calling both of these external functions. We have defined two LOADLIB cards referring to the Fortran and C libraries:

LOADLIB DRESP3 FLIB dresp3_simple_f.dll
LOADLIB DRESP3 CLIB dresp3_simple_c.dll

We have created four DRESP3 cards, which are pointing to the Fortran and C functions and requesting the first and second responses in each of those functions. Two DRESP1 responses are used as parameters:

DRESP3 6 SUMF FLIB MYSUM 1 2
+ DRESP1 2 3
DRESP3 7 AVGF FLIB MYSUM 2 2
+ DRESP1 2 3
DRESP3 8 SUMC CLIB MYSUM 1 2
+ DRESP1 2 3
DRESP3 9 AVGC CLIB MYSUM 2 2
+ DRESP1 2 3

For verification purposes, we have also defined two DRESP2 cards that are pointing to two simple equations which evaluate the sum and the averaged sum of their parameters:

DEQATN 1 F(x,y) = x+y
DEQATN 2 F(x,y) = avg(x,y)

DRESP2 4 SUME 1
+ DRESP1 2 3
DRESP2 5 AVGE 2
+ DRESP1 2 3

Running this input deck through OptiStruct shows that the Fortran external functions, the C external functions and the internal equations always return the same values, and are updated simultaneously throughout the optimization process.

Advanced example

The file dresp3_advanced.F contains the Fortran source code of the second example, in which we are making use of advanced features of the DRESP3 functionality.

The external function is able to compute the von Mises and maximum principal stresses (strains) of an element based on its stress (strains) components. Either 3 or 6 components can be passed as parameters – 3 components for a shell element and 6 components for a solid element. The following features are used:

·      The USRDATA string is parsed to determine whether stresses or strains are requested, and an error message is returned otherwise.

·      The number of parameters is used to determine whether a shell or solid element is treated, and an error message is returned if that number is not equal to 3 or 6.

·      An error message is returned if the parameters are not of type DRESP1 or DRESP1L, since stress or strain components are expected.

·      Even though the function is able to compute two different responses, only the response(s) actually requested by OptiStruct are computed when the function is called.

·      An information message is returned indicating which responses were evaluated.

The input deck dresp3_advanced.fem gives a simple example of problem making use of this external function, for analysis only.

The DRESP1 responses 10-12 and 13-18 correspond to the stress components of a 2-D and a 3-D element, respectively. The DRESP1 responses 20-23 evaluate the von Mises stress and the maximum principal stress of the same two elements:

DRESP1 10 SXX2D STRESS ELEM SX1 100
DRESP1 11 SYY2D STRESS ELEM SY1 100
DRESP1 12 SXY2D STRESS ELEM SXY1 100
DRESP1 13 SXX3D STRESS ELEM SXX 50
DRESP1 14 SYY3D STRESS ELEM SYY 50
DRESP1 15 SZZ3D STRESS ELEM SZZ 50
DRESP1 16 SXY3D STRESS ELEM SXY 50
DRESP1 17 SXZ3D STRESS ELEM SXZ 50
DRESP1 18 SYZ3D STRESS ELEM SYZ 50

DRESP1 20 SVM2D-1 STRESS ELEM SVM1 100
DRESP1 21 SMP2D-1 STRESS ELEM SMP1 100
DRESP1 22 SVM3D-1 STRESS ELEM SVM 50
DRESP1 23 SMP3D-1 STRESS ELEM SMP 50

In addition, we have defined DRESP3 cards which compute the same stress results through our external library. We are also using the SLAVE feature to clone the parameters of similar cards:

DRESP3 30 SVM2D-3 STRLIB GETSTR 1 2
+ DRESP1 10 11 12
+ USRDATA STRESS
DRESP3 31 SMP2D-3 STRLIB GETSTR 2 2
+ SLAVE 30
DRESP3 32 SVM3D-3 STRLIB GETSTR 1 2
+ DRESP1 13 14 15 16 17 18
+ USRDATA STRESS
DRESP3 33 SMP3D-3 STRLIB GETSTR 2 2
+ SLAVE 32