Introducing Adams Solver Libraries

Custom Adams Solver libraries let you use your user-written subroutines with Adams Solver. User-written subroutines let you tailor your template-based product to your needs and go beyond the functionality provided with Adams Solver and the specific solver functionality delivered with your product. For general information about subroutines, see:

For example, you want to create a force element that represents an aircraft landing-gear damper, then you could create a custom Adams Solver library to define the calculations used to produce that force. Inputs to the damper might include damper velocity, damper displacement, and operating temperature. Output could be force.

To use your custom Adams Solver subroutine, you first compile your C or FORTRAN code. You then link those files into an Adams Solver library (*.dll or *.so (on Linux)). The resulting file is stored in a location defined by either MDI_ACAR_SITE or MDI_ACAR_PRIVATE_DIR. When you invoke the site or private solver, the library is automatically loaded and the functions become available (dispatched using the auto-generated code in dispatch.f). A statement in the solver dataset, for the aircraft damper mentioned above, may look like this:

where:

This function would provide the force to the damper element. Assuming that a subroutine named sfo2001 is included in your custom solver code, the general dispatcher will call this subroutine, pass information to the subroutine, and return the force from the subroutine.

Learn more about Adams Solver libraries:

To be able to create Adams View or Adams Solver libraries, you must meet the following requirements:

You can input C or FORTRAN source files to create Adams Solver user libraries and only C source files to create Adams View user libraries. You must compile these subroutines before linking them with an Adams product. See the hardware and software specifications in the Installation Guide that comes with your Adams product for the type of compiler you need (https://simcompanion.hexagon.com/customers/s/article/Adams-Doc-2022-Release). Also refer to your compiler documentation for details.

Therefore, you can write an Adams Solver routine in FORTRAN or C, but keep in mind that:

Before writing user subroutines, make sure you understand the concepts presented in Introducing Adams Solver Libraries and Requirements for Creating Custom Libraries, and more importantly the requirements for the Adams Solver dataset and the naming conventions for the subroutines and files containing subroutines. To review some of those concepts, assume that you have an Adams Solver statement similar to the following:

Then, you would need to generate a file named REQ123.f, which would contain a subroutine named req123. For example:

If you follow this convention, generating your own custom libraries should be easy.

After you created the private Adams Solver library, modify an existing Adams Solver dataset to verify that your custom functions are working. You might find it helpful to write basic 'write' statements in your FORTRAN code to verify that the code is being executed.

Adams Car has a unique utility for dealing with FORTRAN user subroutines called the generalized dispatcher or GENDISP. GENDISP automatically creates the necessary subroutines (REQSUB, SFOSUB, and so on) with all the branches to your routines as part of the linking of a library. The branching for each category of a subroutine (RESQUB, SFOSUB, and so on) are written into a single FORTRAN file named dispatch.f. In the topics that follow you will learn more about how this mechanism works.

Learn why you'll find it valuable to create subroutines and functions and how to create libraries that reference them:

When you write a standard REQSUB subroutine, you often need to process output in more than one way. You might have one subroutine that computes toe, camber, and caster angle, and another that computes lateral acceleration and body sideslip angle. In your dataset you may have the following requests, which reference two user subroutines to calculate toe, camber, and caster, and in the second subroutine lateral acceleration and body sideslip.

The parameters of interest are USER(1, and USER(2, where the values 1 and 2 correspond to PAR(1) in the expression that follows. In your REQSUB, you must have logic to branch to the different subroutines as shown next:

In the above example, if PAR(1) is equal to 1 (as defined by REQUEST/111), then the subroutine TCCREQ is called. Likewise, if PAR(1) is equal to 2 (as defined by REQUEST/222), then the subroutine BSAREQ is called.

Each time you add a new subroutine, you must rewrite your REQSUB to call that subroutine. If your company has a standard REQSUB, you have to create a local version for yourself and then add your subroutines to it.

With the template-based products, however, if you follow a simple naming convention for your user-written subroutines, GENDISP automatically creates a REQSUB, SFOSUB, and so on, with all the branches to your routines as part of the linking of a library. GENDISP places these subroutines in an automatically generated file, named dispatch.f.

For example, if you rename the subroutine TCCREQ to REQ001 and the subroutine BSAREQ to REQ002, then GENDISP creates a REQSUB for you with branches to REQ001 and REQ002 as shown next:

Using GENDISP makes the generation of dispatcher routines a fully automated process, allowing you to concentrate primarily on the content of your solver subroutines.

To use GENDISP correctly, you must do the following:

GENDISP supports the following Adams Solver user-written subroutines. Learn about subroutines.

GENDISP supports the following Adams Car user-written subroutine types:

Adams Car Subroutine Types That GENDISP Supports

Adams Tire now supports dynamic loading (dispatching) of tire (TYRSUB) and road contact (ARCSUB) subroutines. Support for standard driver interface (SDISUB) for lack of usage.

To add support for a new subroutine type, you modify the file dispatch.dat to add the new type. You can find a copy of dispatch.dat in the directory install_dir/product_name/dispatch.dat, where install_dir is the directory in which you installed your template-based product and product_name is acar, aengine, aircraft, or arail, according to the product you are using.

The file, dispatch.dat, is a TeimOrbit format file containing a block for each supported subroutine type and follows these rules:

With this block in dispatch.dat and given a list of files names containing req900, req901, and req221, GENDISP would create the following source code in the file dispatch.f:

Each block for a subroutine in dispatch.dat must contain a (PARAMETERS) sub-block that defines the subroutine parameter types. Optionally, a block may contain a (CODE_BEFORE_BRANCH) sub-block as illustrated in the example MYUSUB shown in Example of Using GENDISP.

The following procedure is only applicable if you want to extend the libraries that GENDISP dispatches. Here we provide an overview of how to test additions to the dispatch.dat file. The result of this procedure should be a fully populated dispatch.f file, which you can examine to verify that valid subroutines have been written. In normal circumstances, this procedure should not required because this process is automated by the acarcom and acarsolvercom scripts. We provide this procedure as a means to validate that you correctly modified the dispatch.dat file.

GENDISP is invoked when linking private or site libraries. A list of standard template-based product file names, plus file names you supply, are passed to GENDISP. GENDISP examines the list of files for names matching the supported subroutine types given in the file dispatch.dat. For each matching name, GENDISP creates a branch in the appropriate user subroutine and outputs the source code file dispatch.f to the working directory.

The file dispatch.f can contain multiple subroutines, but only one of each type (for example, one REQSUB or one CURSUB). The acarcom and acarsolvercom scripts include dispatch.f when linking. The files dispatch.f and dispatch.o are left in the working directory so you can look at them.

For testing or other purposes, you can execute GENDISP yourself. You can find GENDISP at the following location, where install_dir is the installation directory, and product_name is the name of your template-based product:

For example, the location of GENDISP might be:

You invoke GENDISP with the following arguments:

The following example uses GENDISP to generate a MYUSUB that branches to subroutines named myu532, myu253, and so on. It also branches to these subroutines based on an integer argument named SWITCH.

To dispatch.dat, you add a block for MYSSUB that looks like the following:

The code GENDISP generates for MYUSUB looks a little different then the example above, but functions in the same way: