MSC Nastran 2012 User Defined Services

MSC Nastran 2012
User Defined Services

Main Index
Worldwide Web
www.mscsoftware.com
Disclaimer
MSC.Software Corporation reserves the right to make changes in specifications and other information contained
in this document without prior notice.
The concepts, methods, and examples presented in this text are for illustrative and educational purposes only,
and are not intended to be exhaustive or to apply to any particular engineering problem or design. MSC.Software
Corporation assumes no liability or responsibility to any person or company for direct or indirect damages resulting
from the use of any information contained herein.
User Documentation: Copyright 2011 MSC.Software Corporation. Printed in U.S.A. All Rights Reserved.
This notice shall be marked on any reproduction of this documentation, in whole or in part. Any reproduction or
distribution of this document, in whole or in part, without the prior written consent of MSC.Software Corporation is
prohibited.
This software may contain certain third-party software that is protected by copyright and licensed from
MSC.Software suppliers.
MSC, MD, Dytran, Marc, MD Nastran, MSC Nastran, Patran, the MSC.Software corporate logo, OpenFSI and
Simulating Reality are trademarks or registered trademarks of the MSC.Software Corporation in the United States
and/or other countries.
NASTRAN is a registered trademark of NASA. PAMCRASH is a trademark or registered trademark of ESI Group.
SAMCEF is a trademark or registered trademark of Samtech SA. LS-DYNA is a trademark or registered trademark
of Livermore Software Technology Corporation. ANSYS is a registered trademark of SAS IP, Inc., a wholly owned
subsidiary of ANSYS Inc. ABAQUS is a registered trademark of ABAQUS Inc. All other brand names, product
names or trademarks belong to their respective owners. PCGLSS 6.0, Copyright 1992-2005, Computational
Applications and System Integration Inc. All rights reserved. PCGLSS 6.0 is licensed from Computational
Applications and System Integration Inc. METIS is copyrighted by the regents of the University of Minnesota. A
copy of the METIS product documentation is included with this installation. Please see "A Fast and High Quality
Multilevel Scheme for Partitioning Irregular Graphs". George Karypis and Vipin Kumar. SIAM Journal on Scientific
Computing, Vol. 20, No. 1, pp. 359-392, 1999.
Revision 0. November 16, 2011
NA:2012:Z:USERV:DC-USR-PDF
Corporate
MSC.Software Corporation
2 MacArthur Place
Santa Ana, CA 92707
Telephone: (800) 345-2078
FAX: (714) 784-4056
Europe
MSC.Software GmbH
Am Moosfeld 13
81829 Munich
GERMANY
Telephone: (49) (89) 43 19 87 0
Fax: (49) (89) 43 61 71 6
Asia Pacific
MSC.Software Japan Ltd.
Shinjuku First West 8F
23-7 Nishi Shinjuku
1-Chome, Shinjuku-Ku
Tokyo 160-0023, JAPAN
Telephone: 0120-924-832 (toll free,
Japan only)
Mobile phone: 03-6911-1222
Fax: (81) (3)-6911-1201
Main Index
Cont ent s
1 User Defined Subroutines
Introduction 2
Overview 3
Supported User Defined Subroutines 4
Build Environment 5
Path Descriptions 5
Implementation with Templates 6
Implementation without Templates 7
Building the Service 10
Environment Variables 11
Using the Service 12
Error Handling 14
Utility Routines 15
F06 Printing Routine 15
DDOT 15
GMADD 16
GMPRD 16
GMSUB 17
GMTRA 17
GTPRD 18
Invert 3 x 3 Matrix 19
MCPY 19
PRINCV 20
SCLA 21
EXT_USELEM 21
EXT_HYPELA2 27
EXT_UELASTOMER 34
EXT_ORIENT 41
EXT_CRPLAW 44
EXT_UFAIL 49
Main Index

ii
EXT_UPROGFAIL 51
EXT_MOTION 56
EXT_UFRIC 60
EXT_SEPFOR 63
EXT_SEPSTR 66
EXT_UBSQUEAL 68
2 User Defined Module Service UDMSRV
User Defined Module Service UDMSRV 2
Introduction 2
Utility services 4
Memory management interface 5
Database access: 6
3 OpenFSI
Introduction 8
Running an OpenFSI MSC Nastran simulation 11
OpenFSI input deck 11
Running MSC Nastran 19
A simple example model 19
Creating an OpenFSI SCA service 22
Build tools and source files 22
OpenFSI interface and implementation 23
Appendix 25
Interface Definition Language file 25
Service Definition Language file 33
Component Definition Language file 34
OpenFSI data flow 34
Run time errors and debugging 36
References 39
4 OpenFSI MSC Nastran & SimXpert Quick Start Tutorial
Launch SimXpert and Import the Structural Model 42
Define the Service for the Coupled Solution 43
Main Index
iii Contents
Define the OpenFSI LBCs (Wettted Surfaces) 44
Define a Nonlinear Simulation 46
Launch MSC Nastran OpenFSI-AcuSolve Simulation 51
Launch MSC Nastran OpenFSI-MpCCI Simulation (for Fluent & StarCD)
52
Examine the Results Using SimXpert 53
5 OpenMDO
Introduction 2
Run MSC Nastran OpenMDO Optimization 6
OpenMDO Input Deck 6
Running MSC Nastran 6
Creating an OpenMDO SCA service 9
Build tools 9
Build an Example myOpenMDO 9
Building a New OpenMDO Service from Scratch 11
Appendix 13
Interface Definition Language file 13
Reference 16
A Quick Start Guide for User Defined Services
Introduction 18
MSC SDK Delivery Contents 19
Services Implementation Examples 20
Supported Operating Systems and Compilers 21
Compiling User Defined Services 22
Defining the path to User Defined Service 24
Pointing to a User Defined Services from MSC Nastran 25
Running MSC Nastran with a User Defined Service 26
SDK User Services on other Operating Systems 27
Main Index

iv
Errors Messages and Diagnostics 28
FAQ 31
B Compatibility Matrix
Product Compatibility Matrix 34
Main Index
Chapter 1: User Defined Subroutines
User Defined Services Users Guide
1
User Defined Subroutines
Introduction 2
Overview 3
Supported User Defined Subroutines 4
Build Environment 5
Implementation with Templates 6
Implementation without Templates 7
Building the Service 10
Environment Variables 11
Using the Service 12
Error Handling 14
Utility Routines 15
Main Index
Introduction
2
Introduction
The purpose of this manual is to describe the User Defined Services (UDS) capability in MSC Nastran.
This capability in MSC Nastran gives you a mechanism to utilize your own user subroutines or
applications within an MSC Nastran execution. There are many benefits to this new feature, such as using
your own proprietary element formulations. You can also use this feature to extend MSC Nastrans
material property formulations or apply specific rules to a contact problem. The tools provided can be
used to integrate your own CFD application within MSC Nastran. The Quick Start Guide for User Defined
Services (App. A) describes how to compile and run the user defined services examples delivered with
MSC Nastran.
Main Index
3 Chapter 1: User Defined Subroutines
Overview
Overview
The process of enabling User Defined Services in MSC Nastran consists of the following four steps:
1. Creating the desired implementation for the User Defined Services in the form of dynamic-link
libraries.
2. Defining the location of the user defined service, service catalogue, and service resource
directory.
3. Specifying the proper commands in the model to load the service.
4. Identifying the elements that use the user supplied implementation.
In order to create a dynamic-link library suitable for usage with MSC Nastran, a build environment is
delivered to assist users in building the library. Please refer to the SCA Service Guide document that
describes the features and capabilities of the build system.
Included in the MSC Nastran installation are implementation templates for user subroutines. These
templates simplify the implementation of user subroutines, and can be found in the following directory
tree:
<msc_base>/nastran/prod_ver/nast/services/Implementations/{Contact, Elements, Materials, OpenFSI,
OpenMDO, Udmsrv}
Main Index
Supported User Defined Subroutines
4
Supported User Defined Subroutines
Contact
motion rigid surface motion
sepfor separation force
sepstr separation stress
ufric friction coefficients
ubsqueal friction coefficient and effective stiffness in brake squeal analysis
Elements
nlrsfd nonlinear transient load proportional to a squeeze film damper
uselem user-defined element
Materials
crplaw specify increment of creep strain
hypela2 implement arbitrary material models in conjunction with the hypoelastic model
orient specification of preferred orientation
uelastomer generalized strain energy function
ufail user-defined failure criterion
uprogfail definition of material stiffness reduction factors for progressive failure analysis
Main Index
Build Environment
Build Environment
In order to build User Defined Services, the build environment has to be properly configured. Chapter 3
of the SCA service guide details the process of setting up the build environment. Once the build
environment is setup properly you can easily build service libraries.
For this release, the build environment requires proper compiler versions to be installed on the target
platform. On Windows (32 and 64 bit), Microsoft Visual Studio 2005, Service pack 1 has to be installed
on the target machine. On Linux (32 and 64 bit), Intel C++ compiler version 10 is required. Please consult
the SCA Service Guide for the compiler requirements on other platforms. In addition to C++ compilers,
you may need to install Fortran compilers, if you want to take advantage Fortran templates for user
subroutines. The required version of Intel Fortran compilers are 10.1 (both on Windows and Linux).
Path Descriptions
msc_base: path of the MSC Software base directory.
SCA_OBJECT: path of directory tree containing all temporary files generated by the build. Included are
source files, object files, and libraries.
APPS_LOCAL: path of directory tree containing copies of the files generated during a build that will
override or add to the files in the SCA application system tree.
The SCA_OBJ and APPS_LOCAL paths are chosen by the user and can optionally be set by creating or
modifying a SCons configuration file in the home directory: SConopts.user. If this file exists with values
for SCA_OBJ and APPS_LOCAL defined, they do not have to be specified in the build command. For
the APPS2_SYSTEM variable, <msc_base> has to be replaced with the correct MSC base path prior to
building.
Sample SConopts.user file with undefined paths:
BUILDTYPE = 'opt'
APPS_DIR = 'SCAKernel'
TOOLS_DIR = 'Tools'
PRODUCT_LINE = 'nastran'
if (SCASCons.MACHINE).startswith('WIN'):
SCA_OBJECT = '<SCA_OBJECT_PATH>'
APPS_LOCAL = '<APPS_LOCAL_PATH>'
else:
SCA_OBJECT = '<SCA_OBJECT_PATH>'
APPS_LOCAL = '<APPS_LOCAL_PATH>'
Main Index
Implementation with Templates
6
Implementation with Templates
The user subroutines can be implemented in either C++ or FORTRAN. Calls to the FORTRAN
subroutines originate from their respective C++ implementation, so modifying the C++ function body is
not recommended if that particular subroutine will be implemented in FORTRAN.
Source files in C++ contain both 32 bit versions and 64 bit versions and may also contain various user
subroutines, whereas FORTRAN source files have only a single version. Source files containing various
user subroutines are either of type contact or material.
Contact.cpp (motion, sepfor, sepstr, ubsqueal, ufric)
Materials.cpp (crplaw, hypela2, orient, uelastomer, ufail, uprogfail)
To begin the implementation process, copy the <msc_base>/nastran/prod_ver/nast/services/ directory to
a directory with write access, then modify the desired user subroutine in either C++ or FORTRAN.
C++ implementations:
<msc_base>/nastran/prod_ver/nast/services/Implementations/Contact/src/Contact.cpp
<msc_base>/nastran/prod_ver/nast/services/Implementations/Elements/src/Nlrsfd/Nlrsfd.cpp
<msc_base>/nastran/prod_ver/nast/services/Implementations/Elements/src/uselem/uselem.cpp
<msc_base>/nastran/prod_ver/nast/services/Implementations/Materials/src/Materials.cpp
FORTRAN implementations:
<msc_base>/nastran/prod_ver/nast/services/Implementations/Contact/src/motion/ext_motion.F
<msc_base>/nastran/prod_ver/nast/services/Implementations/Contact/src/sepfor/ext_sepfor.F
<msc_base>/nastran/prod_ver/nast/services/Implementations/Contact/src/sepstr/ext_sepstr.F
<msc_base>/nastran/prod_ver/nast/services/Implementations/Contact/src/ubsqueal/ext_ubsqueal.F
<msc_base>/nastran/prod_ver/nast/services/Implementations/Contact/src/ufric/ext_ufric.F
<msc_base>/nastran/prod_ver/nast/services/Implementations/Elements/src/Nlrsfd/ext_nlrsfd.F
<msc_base>/nastran/prod_ver/nast/services/Implementations/Elements/src/thpad/ext_thpad.F
<msc_base>/nastran/prod_ver/nast/services/Implementations/Elements/src/uselem/ext_uselem.F
<msc_base>/nastran/prod_ver/nast/services/Implementations/Materials/src/crplaw/ext_crplaw.F
<msc_base>/nastran/prod_ver/nast/services/Implementations/Materials/src/hypela2/ext_hypela2.F
<msc_base>/nastran/prod_ver/nast/services/Implementations/Materials/src/orient/ext_orient.F
<msc_base>/nastran/prod_ver/nast/services/Implementations/Materials/src/uelastomer/ext_uelast
omer.F
<msc_base>/nastran/prod_ver/nast/services/Implementations/Materials/src/ufail/ext_ufail.F
<msc_base>/nastran/prod_ver/nast/services/Implementations/Materials/src/uprogfail/ext_uprogfa
il.F
Main Index
Implementation without Templates
Without using the provided templates in the SDK, the first step in implementing a user defined subroutine
is to create a service definition language (SDL) file and component definition language (CDL) file. These
two files correspond to one or more interface definition language (IDL) files. The IDL files for user
subroutines are provided in the installation.
The next step is to generate the skeleton file for the service. The build environment provides a tool,
namely genskeleton, to generate the desired skeleton file from an IDL, SDL, and CDL file. Once the
skeleton file is generated, you can add the desired functionality to the appropriate methods within the
service. By default, the generated skeleton files will be a C++ source and header file. For further
information on how to invoke the genskeleton program, please refer to SCA Service Guide document.
For illustration purposes, lets assume that you have decided to create a service within Test name space
for the NLRSFD user subroutine, and the intention is to only implement the interface that is provided by
its IDL.
The following code example illustrates the content of the sdl file:
#ifndef TEST_SDL_INCLUDED
#define TEST_SDL_INCLUDED
#include "SCA/MDSolver/Obj/Uds/Elements/Nlrsfd/nlrsfd.idl"
module Test {
service Test.Nlrsfd
{
interface
SCA::MDSolver::Obj::Uds::Elements::Nlrsfd::SCAIMDSolverNlrsfd;
};
}; // Test
#endif
Similarly, the CDL file contains the definition of service (or services), which will form the component.
An example for a CDL file is illustrated below:
#ifndef TEST_NLRSFD_CDL_INCLUDED
#define TEST_NLRSFD_CDL_INCLUDED
#include "test.sdl"
component myTest
{
service Test.Nlrsfd;
};
#endif
Upon generating the skeleton file with the above, the C++ source file will contain 4 methods:
1. Constructor (a method which is automatically invoked when the service is created)
Main Index
8
2. Destructor (a method which is automatically invoked when the service is destroyed)
3. runNlrsfd (the functional method)
4. runNlrsfd_64 (the 64-bit functional method for ILP64)
The constructor method is called each time the service is initiated. Similarly the destructor method is
called each time the service is terminated. The runNlrsfd method is the functional method in which you
can add your specific implementation, and runNlrsfd_64 for implementations for ILP64 mode.
The runNlrsfd method implements the static signature defined by the MSC Nastran application, and will
be called by the MSC Nastran application while processing the non-linear force (NLRSFD) entries of the
input file. Using the parameters passed to runNlrsfd method, you will have access to all arguments that
are set through the NLRSFD entry at input. You can implement your formulation and update the
following parameters, returning back to MSC Nastran:
SCAReal64 fx,
SCAReal64 fy,
SCAInt32 fuseit,
SCAInt32 bisect,
SCAReal32 parm1,
SCAReal32 parm2,
SCAReal32 parm3,
SCAReal32 parm4,
SCAReal32 parm5,
SCAReal32 parm6,
SCAReal32 parm7,
SCAReal32 parm8.
More information on these parameters is given in the following sections.
#include "Nlrsfd.h"
namespace Test {
// Constructor
Nlrsfd::Nlrsfd(SCAINlrsfdFactoryAccess* factoryAccess) :
NlrsfdBase(factoryAccess)
{
}
// Destructor
Nlrsfd::~Nlrsfd()
{
}
SCAResult Nlrsfd::runNlrsfd(const SCAInt32 sid, const SCAInt32 ga, const
SCAInt32 gb,
const SCAString plane, const SCAReal32 bdia, const SCAReal32 blen, const
SCAReal32 bclr,
const SCAString soln, const SCAReal32 visco, const SCAReal32 pvapco,
const SCAInt32 nport, const SCAReal32 pres1, const SCAReal32 theta1,
const SCAReal32 pres2, const SCAReal32 theta2, const SCAInt32 npnt,
const SCAReal32 offset1, const SCAReal32 offset2, const SCAString evalname,
const SCAReal32 time, const SCAReal64 xx, const SCAReal64 yy, const SCAReal64
xdt,
Main Index
const SCAReal64 ydt, const SCAReal64 xb, const SCAReal64 yb, const SCAReal64
xbt,
const SCAReal64 ybt, SCAReal64& fx, SCAReal64& fy, SCAInt32& fuseit,
SCAInt32& bisect, SCAReal32& parm1, SCAReal32& parm2, SCAReal32& parm3,
SCAReal32& parm4, SCAReal32& parm5, SCAReal32& parm6, SCAReal32& parm7,
SCAReal32& parm8, const SCAReal32 omega)
{
return SCASuccess;
}
SCAResult Nlrsfd::runNlrsfd_64(const SCAInt64 sid, const SCAInt64 ga, const
SCAInt64 gb,
const SCAString plane, const SCAReal64 bdia, const SCAReal64 blen, const
SCAReal64 bclr,
const SCAString soln, const SCAReal64 visco, const SCAReal64 pvapco,
const SCAInt64 nport, const SCAReal64 pres1, const SCAReal64 theta1,
const SCAReal64 pres2, const SCAReal64 theta2, const SCAInt64 npnt,
const SCAReal64 offset1, const SCAReal64 offset2, const SCAString evalname,
const SCAReal64 time, const SCAReal64 xx, const SCAReal64 yy, const SCAReal64
xdt,
const SCAReal64 ydt, const SCAReal64 xb, const SCAReal64 yb, const SCAReal64
xbt,
const SCAReal64 ybt, SCAReal64& fx, SCAReal64& fy, SCAInt64& fuseit,
SCAInt64& bisect, SCAReal64& parm1, SCAReal64& parm2, SCAReal64& parm3,
SCAReal64& parm4, SCAReal64& parm5, SCAReal64& parm6, SCAReal64& parm7,
SCAReal64& parm8, const SCAReal64 omega)
{
return SCASuccess;
}
}
Main Index
Building the Service
10
Building the Service
To build the service, execute the scons command at the top level of the source tree. The build
environment will compile and link all necessary files, including the modifications to any user subroutine
within the source tree. A dynamically loaded library is created and will later be used by the MSC Nastran
application at runtime.
If the SConopts.user file does not exist in the home directory or if the paths are not defined in that file,
the SCA_OBJECT, APPS_LOCAL, and APPS2_SYSTEM paths must be specified when running scons
(provided by the MSC Software Development Kit).
To build the service with SCons, enter the following command:
<msc_base>/msc_sdk<prod_ver>/Tools/scons SCA_OBJECT=<SCA_OBJECT_PATH>
APPS_LOCAL=<APPS_LOCAL_PATH>
Main Index
Environment Variables
Environment Variables
In order to load the generated User Defined Service, within the launch environment, three new
environment variables have to be set:
SCA_LIBRARY_PATH - points to the location where the libraries are to be found.
SCA_SERVICE_CATALOG - points to the location of the SCA service catalog.
SCA_RESOURCE_DIR - points to the location of SCA resource directory.
Presence of these three environment variables ensures proper loading of user defined services. For the
example provided earlier in this document, these three environment variables should be set as following:
Windows (32 bit):
set SCA_LIBRARY_PATH=<APPS_LOCAL>\WINNT\lib
set SCA_SERVICE_CATALOG=<APPS_LOCAL>\res\SCAServiceCatalog.xml
set SCA_RESOURCE_DIR=<APPS_LOCAL>\res
Windows (64 bit):
set SCA_LIBRARY_PATH=<APPS_LOCAL>\WIN8664\lib
set SCA_SERVICE_CATALOG=<APPS_LOCAL>\res\SCAServiceCatalog.xml
set SCA_RESOURCE_DIR=<APPS_LOCAL>\res
Linux (32 bit):
set SCA_LIBRARY_PATH=<APPS_LOCAL>/LX86/lib
set SCA_SERVICE_CATALOG=<APPS_LOCAL>/res/SCAServiceCatalog.xml
set SCA_RESOURCE_DIR=<APPS_LOCAL>/res
Linux (64 bit):
set SCA_LIBRARY_PATH=<APPS_LOCAL>/LX8664/lib
set SCA_SERVICE_CATALOG=<APPS_LOCAL>/res/SCAServiceCatalog.xml
set SCA_RESOURCE_DIR=<APPS_LOCAL>/res
Main Index
Using the Service
12
Using the Service
In this section we will describe the modifications to the input file required for using the user defined
service.
In order to identify the service, you will have to create a connection between the service name and a
service identifier. This is done through the connect statement in the FMS statement. The syntax for new
connect entry is as follows:
connect service <group_name> <service_name>
Where group_name is a name tag (8 characters long) which will be used to identify the service
implementation to be used for a specific bulk data entry, and service_name is the name of service, for
example:
connect service contact SCA.MDSolver.Obj.Uds.Contact
creates a group_name servide identifier contact, which points to the
SCA.MDSolver.Util.Ums service.
Available service names for the user subroutines (based on the example implementations) include
SCA.MDSolver.Obj.Uds.Contact (motion, sepfor, sepstr, ubsqueal, ufric)
SCA.MDSolver.Obj.Uds.Elements.Nlrsfd
SCA.MDSolver.Obj.Uds.Elements.uselem
SCA.MDSolver.Obj.Uds.Materials (crplaw, hypela2, orient, uelastomer, ufail, uprogfail)
To trigger the service, an appropriate bulk data entry has to be associated with the group name while also
specifying the user subroutine in the user subroutine name field of the entry except for NLRSFD since
its card does not have a user subroutine field.
Currently available cards for each category of user subroutines comprise
BCONUDS contact user subroutines
ELEMUDS element user subroutines
MATUDS material user subroutines
NLRSFD non-linear squeeze film damper user subroutine
For the UDS cards, each has a field for a referenced ID and its type, a group name, a user subroutine
name, and optional auxiliary user data (integers, real, and characters). The format for BCONUDS can be
seen below. See the Nastran QRG for the format of the relevant entries.
BCONUDS <body_id> <body_type> <group_name> <usersub_name>
INT <integer>
REAL <real>
CHAR <char>
The lines for the auxiliary data may be omitted as they are optional, but the other fields are required.
Main Index
Using the Service
The New IFP system is required for user defined subroutines and is enabled through system cell 444. To
use New IFP when running the input file, append sys444=1 to the Nastran submittal command argument
list. For instance,
prod_ver sys444=1 job.dat
Input file example for motion:

connect service contact 'SCA.MDSolver.Obj.Uds.Contact'
...
SOL 400
...
BEGIN BULK
...
BCONUDS 7 BCBODY contact motion
INT 1337 2 3 4 5 6 7
REAL 3.1415 2.2 3.3 4.4
CHAR FOO B111B22 C111C22 D111D22 E11
BCBODY 7 2D RIGID 0 0 1 0
...
Main Index
Error Handling
14
Error Handling
The current implementation provides a limited means for error handling. Upon return from a user defined
service method, the value of the return call will be examined. SCASuccess is a constant equal to zero,
and if that is returned, the MSC Nastran application assumes that the execution of the User Defined
Service has been successful. Anything other than zero is viewed as an error. In the FORTRAN user
subroutine implementations, the error code can be set through the error_code variable. MSC Nastran
upon return to the main application will evaluate this return code and will terminate the application if its
value is not zero. A message including the non-zero return value is printed in the output file (f06).
Main Index
Utility Routines
Utility Routines
F06 Printing Routine
The printf06 function provides a mechanism to write a line to the F06 file. It takes a character string as
an argument and returns a SCAResult of integer type. The following is an example of how it can be used
in a user subroutine:
integer, external :: printf06
integer :: scareturn
scareturn = printf06(foo)
scareturn = printf06(bar)
DDOT
Inner Product of Two Vectors
Description
Returns the dot product of two vectors.
Format
Utility function DDOT can be used in the following format:
DDOT(NN, A, IA, B, IB, ANS)
where:
Input:
NN number of items in each vector to be used
A first input vector
IA stride in vector A
B second input vector
IB stride in vector B
Required Output:
ANS inner product of vectors A and B
Note: Vectors A, B, and ANS are real*8 variables.
Main Index
Utility Routines
16
GMADD
Matrix Add
Description
Add two matrices and put sum into third matrix.
Format
Utility routine GMADD can be called with the following format:
GMADD(W, X, Y, N, M)
where:
Input:
W first input matrix
X second input matrix
N first dimension of W, X, and Y
M second dimension of W, X, and Y
Required Output:
Y output matrix, Y = W + X
GMPRD
Matrix Product
Description
Multiply two matrices and put product in third matrix.
Format
Utility routine GMPRD can be called with the following format:
GMPRD (W, X, Y, N, M)
where:
Input:
N first dimension of W and Y
Note: Matrices W, X, and Y are real*8 arrays.
Main Index
Utility Routines
M second dimension of W and first dimension of X
L second dimension of X and Y
Required Output:
Y output matrix, Y = W * X
GMSUB
Matrix Subtract
Description
Subtract two matrices and put remainder in third matrix.
Format
Utility routine GMSUB can be called with the following format:
GMSUB (W, X, Y, N, M)
where:
Input:
N first dimension of W, X, and Y
M second dimension of W, X, and Y
Required Output:
Y output matrix, Y = W X
GMTRA
Matrix Transpose
Description
Transpose a matrix.
Format
Utility routine GMTRA can be called with the following format:
Main Index
Utility Routines
18
GMTRA (W, X, N, M)
where:
Input:
W input matrix
N first dimension of W and second dimension of X
M second dimension of W and first dimension of X
Required Output:
X output matrix X = W
T
GTPRD
Transpose Matrix Product
Description
Transpose product of two matrices.
Format
Utility routine GTPRD can be called with the following format:
GTPRD (W, X, Y, N, M, L)
where:
Input:
N first dimension of W and X
M second dimension of W and first dimension of Y
L second dimension of X and Y
Required Output:
Y output matrix Y = W
T
*X
Note: Matrices W and X are real*8 matrices.
Note: Matrices W, X, and Y are real*8 matrices.
Main Index
Utility Routines
Invert 3 x 3 Matrix
Description
Invert 3 x 3 matrices.
Format
Utility routine INV3X3 can be called with the following format:
INV3X3(A, AINV, DET, IFLAG)
where:
Input:
A input matrix
IFLAG flag for output
Required Output:
A inverse of input matrix A if IFLAG = 1
AINV inverse of input matrix A if IFLAG is not = 1
DET determinant of A
MCPY
Matrix Copy
Description
Copy a matrix.
Format
Utility routine MCPY can be called with the following format:
MCPY(W, X, N, M, MS)
where:
Input:
W input matrix
N first dimension of W and X
M second dimension of W and X
Note: Matrices A, AINV, and scalar DET are real*8 variables.
If DET = 0, the matrix is singular and the inverse is not calculated.
Main Index
Utility Routines
20
MS not used
Required Output:
X output matrix, X = W
PRINCV
Find Principle Values
Description
Solves 3 x 3 Eigen problem with Jacobi transformations to find principle values of stresses and strains.
Format
Utility routine PRINCV can be called with the following format:
PRINCV(PV, R, V, NDI, NSHEAR, ISS, JCR1, JCR2, JCR3)
where:
Input:
V(6) vector of strains or stresses.
NDI number of direct stress or strain components.
NSHEARnumber of shear stress or strain components.
ISS flag to indicate whether V is stress or strain.
if ISS = 0, V is stress
if ISS = 1, V is strain
JCR1 set to 0
JCR2 set to 0
JCR3 set to 0
Required Output:
PV(3) vector of principal values
R(3,3) matrix of principal directions
Note: Matrices W and X are real*8 arrays.
Note: Vectors and matrices PV, R, and V are real*8 arrays.
Main Index
Utility Routines
SCLA
Set Matrix to Value
Description
Assign a scalar value to a matrix.
Format
Utility routine SCLA can be called with the following format:
SCLA (W, C, N, M, MS)
where:
Input:
W input matrix
C scalar
N first dimension of W
M second dimension of W
MS not used
Required Output:
W output matrix
EXT_USELEM
User-defined Element
Description
This user subroutine allows the user to calculate his own finite element stiffness or mass matrix. This can
also be used as interface with other numerical techniques. In general, in the finite element calculation,
several matrices are required; hence, for a particular element, this user subroutine is called a multiple
number of times. The calls and the users requirements are defined as follows:
Note: Matrix W and scalar C are real*8 variables.
Main Index
Utility Routines
22
Using this option, user can only define an element similar to an existing Nastran element types, such that
all user element properties including dimensions, connectivity and integration points will be the same as
this Nastran element type.
A virtual material type must be defined and assigned to the property definition option associated with
user elements. Otherwise, the program will exit with input errors.
The subroutine is activated by ELEMUDS bulk data option. ELEMUDS defines the service name
associated with the user subroutine, and the data (integer, real and characters) to be used in the user
subroutine. It should look like the following for EXT_USELEM application:
ELEMUDS,pid,ptype,sname,uselem,
,INT,
,REAL,
,CHAR,
Where ptype is the property type associated with the user-defined elements, pid is the property
identification number of ptype, and sname is the name of this service. Integers (real numbers, characters)
can be defined and passed into EXT_USELEM with the key word INT (REAL, CHAR).
Format
IDL
module SCA {
module MDSolver {
module Obj {
module Uds {
module Elements {
module uselem {
typedef SCAInt32 DynInt32[];
IFLAG=2 Return the element tangent stiffness matrix (K). For an elastic analysis, this is the usual
stiffness. For a heat transfer matrix analysis, this is the conductivity matrix. Also
calculate the total internal forces (R). This is not necessary in a linear elastic analysis.
IFLAG=3 Return the mass matrix (M) for a dynamic analysis or specific heat matrix for a heat
transfer problem.
IFLAG=4 Calculate the incremental strains (DE), generalized stresses (GSIGS) and the internal
force (R). For a linear elastic solution, if only displacements are required, the user does
not need to return any values. In a heat transfer analysis, the thermal gradient and the
heat fluxes (both stored via SIGXX) and the internal flux vector (R) need to be calculated.
Main Index
Utility Routines
typedef SCAReal64 DynReal64[];
typedef SCAReal64 DynReal64_2[][];
interface SCAIMDSolverUselem : SCAIService
{
SCAResult usrUselem_32( in SCAInt32 m,
out DynReal64_2 xk,
out DynReal64_2 xm,
in SCAInt32 nnode,
in SCAInt32 ndeg,
out DynReal64_2 f,
out DynReal64_2 r,
in SCAInt32 jtype,
in DynReal64_2 dispt,
in DynReal64_2 disp,
in SCAInt32 ndi,
in SCAInt32 nshear,
in SCAInt32 ipass,
in SCAInt32 nstats,
in SCAInt32 ngenel,
in SCAInt32 intel,
in DynReal64_2 coord,
in SCAInt32 ncrd,
in SCAInt32 iflag,
in SCAInt32 idss,
in DynReal64_2 t,
in DynReal64_2 dt,
out DynReal64_2 etota,
out DynReal64_2 gsigs,
out DynReal64_2 de,
in DynReal64 geom,
in DynInt32 jgeom,
out DynReal64_2 sigxx,
in SCAInt32 nstrmu,
in DynInt32 idata,
in DynReal64 rdata,
in DynInt32 cidata );
SCAResult usrUselem_64( in SCAInt64 m,
out DynReal64_2 xk,
out DynReal64_2 xm,
in SCAInt64 nnode,
in SCAInt64 ndeg,
out DynReal64_2 f,
out DynReal64_2 r,
in SCAInt64 jtype,
in SCAInt64 ndi,
in SCAInt64 nshear,
in SCAInt64 ipass,
in SCAInt64 nstats,
in SCAInt64 ngenel,
Main Index
Utility Routines
24
in SCAInt64 intel,
in SCAInt64 ncrd,
in SCAInt64 iflag,
in SCAInt64 idss,
in DynReal64_2 t,
in DynReal64_2 dt,
out DynReal64_2 etota,
out DynReal64_2 gsigs,
out DynReal64_2 de,
in DynReal64 geom,
in DynInt64 jgeom,
out DynReal64_2 sigxx,
in SCAInt64 nstrmu,
in DynInt64 idata,
in DynReal64 rdata,
};
}; // uselem
}; // Elements
}; // Uds
}; // Obj
}; // MDSolver
}; // SCA
C++
SCAResult uselem::usrUselem_32(const SCAInt32 m, DynReal64_2& xk, DynReal64_2& xm, const SCAInt32 nnode, const
SCAInt32 ndeg,
DynReal64_2& f, DynReal64_2& r, const SCAInt32 jtype, const DynReal64_2& dispt,
const DynReal64_2& disp, const SCAInt32 ndi, const SCAInt32 nshear, const SCAInt32
ipass,
const SCAInt32 nstats, const SCAInt32 ngenel, const SCAInt32 intel, const DynReal64_2&
coord,
const SCAInt32 ncrd, const SCAInt32 iflag, const SCAInt32 idss, const DynReal64_2& t,
const DynReal64_2& dt, DynReal64_2& etota, DynReal64_2& gsigs, DynReal64_2& de,
const DynReal64& geom, const DynInt32& jgeom, DynReal64_2& sigxx, const SCAInt32 nstrmu,
const DynInt32& idata, const DynReal64& rdata, const DynInt32& cidata)
{
return SCASuccess;
}
SCAResult uselem::usrUselem_64(const SCAInt64 m, DynReal64_2& xk, DynReal64_2& xm, const SCAInt64 nnode, const
SCAInt64 ndeg,
DynReal64_2& f, DynReal64_2& r, const SCAInt64 jtype, const DynReal64_2& dispt,
const DynReal64_2& disp, const SCAInt64 ndi, const SCAInt64 nshear, const SCAInt64
ipass,
const SCAInt64 nstats, const SCAInt64 ngenel, const SCAInt64 intel, const DynReal64_2&
coord,
const SCAInt64 ncrd, const SCAInt64 iflag, const SCAInt64 idss, const DynReal64_2& t,
const DynReal64_2& dt, DynReal64_2& etota, DynReal64_2& gsigs, DynReal64_2& de,
const DynReal64& geom, const DynInt64& jgeom, DynReal64_2& sigxx, const SCAInt64 nstrmu,
const DynInt64& idata, const DynReal64& rdata, const DynInt64& cidata)
{
return SCASuccess;
}
FORTRAN
subroutine ext_uselem(m, ipid, iptyp, xk, xm, nnode, ndeg, f, r,
& jtype, dispt, disp, ndi, nshear, ipass, nstats,
Main Index
Utility Routines
& ngenel, intel, coord, ncrd, iflag, idss, t, dt,
& etota, gsigs, de, geom, jgeom, sigxx, nstrmu, idata,
& rdata, cdata, len_idata, len_rdata, len_cdata,
& error_code)
implicit none
integer, intent(in) :: len_idata, len_rdata, len_cdata
integer, intent(in) :: m, ipid, iptyp, nnode, ndeg, jtype, ndi
integer, intent(in) :: nshear, ipass, nstats, ngenel, intel, ncrd
integer, intent(in) :: iflag, idss, nstrmu
integer, intent(out) :: error_code
integer, intent(in), dimension(8) :: jgeom
real(8), intent(out), dimension(idss, idss) :: xk, xm
real(8), intent(out), dimension(ndeg, nnode) :: f, r
real(8), intent(in), dimension(ndeg, nnode) :: dispt, disp
real(8), intent(in), dimension(ncrd, nnode) :: coord
real(8), intent(in), dimension(nstats, intel) :: t, dt
real(8), intent(out), dimension(ngenel, intel) :: etota, gsigs, de
real(8), intent(in), dimension(8) :: geom
real(8), intent(out), dimension(nstrmu, intel) :: sigxx
integer, intent(in), dimension(len_idata) :: idata
real(8), intent(in), dimension(len_rdata) :: rdata
character(len=8), intent(in), dimension(len_cdata) :: cdata
end subroutine ext_uselem
Required Input:
M is the user element number.
NNODE is the number of nodes per element.
NDEG is the maximum number of degrees of freedom per node.
JTYPE is the user element type (negative).
DISPT is the total nodal displacements array of this element.
In heat transfer, DISPT is the temperature array at which material properties were last
calculated.
DISP is the incremental nodal displacements of this element.
In heat transfer, DISP is the total current nodal temperatures of this element.
NDI is the number of direct components of stress/internal heat flux.
NSHEAR is the number of shear components of stress.
In heat transfer, NSHEAR is zero.
IPASS Flag to indicate which pass for coupled analysis.
= 1 during a stress analysis pass.
= 2 during a heat transfer pass.
Main Index
Utility Routines
26
NSTATS is the number of state variables. 1 for MSC Nastran
NGENEL is the number of generalized strains.
INTEL is the number of integration points.
COORD is the original nodal coordinates array.
NCRD is the number of coordinates per node.
IFLAG indicates what is to be returned by the user.
= 2 Called by OASEMB during formation of stiffness matrix.
You return XK,R.
= 3 Called by OASMAS during formation of mass matrix.
The user returns XM.
= 4 Called by OGETST during stress recovery.
The user returns R,GSIGS,DE,ETOTA,SIGXX for stress analysis pass.
The user returns R, SIGXX for heat transfer pass.
IDSS is the size of element stiffness matrix.
T(1) is the temperature.
DT(1) is the increment of temperature.
GEOM is the array of the geometric parameters. (not used for MSC Nastran)
JGEOM is the array of table ids for the geometric parameters. (not used for MSC Nastran)
NSTRMU is the number of stresses/heat fluxes per integration points.
Required Output:
XK is the stiffness matrix or conductivity matrix.
XM is the mass matrix or specific heat matrix.
F is the externally applied equivalent nodal loads/nodal fluxes array.
R is the internal forces/fluxes array.
ETOTA is the total strain array.
Not used in heat transfer.
GSIGS is the generalized stress array.
DE is the increment of strain array.
Main Index
Utility Routines
EXT_HYPELA2
User-defined Material Behavior
Description
This user subroutine gives the user the ability to implement arbitrary material models in conjunction with
the MATUSR bulk data option. The program supplies the user with the total displacement, incremental
displacement, total mechanical strain (mechanical strain = total strain thermal strain), the increment of
mechanical strain, and other information. Stress, total strain, and state variable arrays at the beginning of
the increment are passed to EXT_HYPELA2. The user is expected to calculate stresses S, tangent
stiffness D, and state variables (if present) that correspond to the current strain at the end of the increment
.
The subroutine is activated by MATUSR along with MATUDS bulk data options. MATUDS defines the
service name corresponding to the material, and the data (integer, real and characters) used to define the
material properties in the user subroutine. It should look like the following for EXT_HYPELA2
application:
MATUDS,mid,MATUSR,sname,HYPELA2,
,INT,
,REAL,
,CHAR,
Where mid is the material identification number consistent with MATUSR and sname is the name of this
service. Integers (real numbers, characters) can be defined and passed into EXT_HYPELA2 with the key
word INT (REAL, CHAR).
Format
IDL
module SCA {
module MDSolver {
module Obj {
module Uds {
module Materials {
module hypela2 {
SIGXX is layer stresses for shell elements and is equal to GSIGS for continuum element.
In the heat transfer pass, SIGXX contains the thermal gradients and the heat fluxes.
t t
n
= ( )
t t
n 1 +
= ( )
Main Index
Utility Routines
28
interface SCAIMDSolverHypela2 : SCAIService
{
SCAResult usrHypela2_32( out DynReal64_2 d,
out DynReal64 g,
in DynReal64 e,
in DynReal64 de,
out DynReal64 s,
in DynReal64 t,
in DynReal64 dt,
in SCAInt32 ngens,
in DynInt32 n,
in SCAInt32 nn,
in DynInt32 kcus,
in DynInt32 matus,
in SCAInt32 ndi,
in SCAInt32 nshear,
in DynReal64_2 ffn,
in DynReal64_2 frotn,
in DynReal64 strechn,
in DynReal64_2 eigvn,
in DynReal64_2 ffn1,
in DynReal64_2 frotn1,
in DynReal64 strechn1,
in DynReal64_2 eigvn1,
in SCAInt32 ncrd,
in SCAInt32 itel,
in SCAInt32 ndeg,
in SCAInt32 ndm,
in SCAInt32 nnode,
in SCAInt32 jtype,
in DynInt32 lclass,
in SCAInt32 ifr,
in SCAInt32 ifu,
in SCAInt32 nstats,
in SCAInt32 isunit,
in DynInt32 idata,
in DynReal64 rdata,
SCAResult usrHypela2_64( out DynReal64_2 d,
out DynReal64 g,
in DynReal64 e,
in DynReal64 de,
out DynReal64 s,
in DynReal64 t,
in DynReal64 dt,
in SCAInt64 ngens,
in DynInt64 n,
in SCAInt64 nn,
Main Index
Utility Routines
in DynInt64 kcus,
in DynInt64 matus,
in SCAInt64 ndi,
in SCAInt64 nshear,
in DynReal64_2 ffn,
in DynReal64_2 frotn,
in DynReal64 strechn,
in DynReal64_2 eigvn,
in DynReal64_2 ffn1,
in DynReal64_2 frotn1,
in DynReal64 strechn1,
in DynReal64_2 eigvn1,
in SCAInt64 ncrd,
in SCAInt64 itel,
in SCAInt64 ndeg,
in SCAInt64 ndm,
in SCAInt64 nnode,
in SCAInt64 jtype,
in DynInt64 lclass,
in SCAInt64 ifr,
in SCAInt64 ifu,
in SCAInt64 nstats,
in SCAInt64 isunit,
in DynInt64 idata,
in DynReal64 rdata,
};
}; // hypela2
}; // Materials
}; // Uds
}; // Obj
}; // MDSolver
}; // SCA
C++
SCAResult Materials::usrHypela2_32(hypela2::DynReal64_2& d, hypela2::DynReal64& g, const hypela2::DynReal64& e,
const hypela2::DynReal64& de, hypela2::DynReal64& s, const hypela2::DynReal64& t,
const hypela2::DynReal64& dt, const SCAInt32 ngens, const hypela2::DynInt32& n,
const SCAInt32 nn, const hypela2::DynInt32& kcus, const hypela2::DynInt32& matus,
const SCAInt32 ndi, const SCAInt32 nshear, const hypela2::DynReal64_2& disp,
const hypela2::DynReal64_2& dispt, const hypela2::DynReal64_2& coord,
const hypela2::DynReal64_2& ffn, const hypela2::DynReal64_2& frotn,
const hypela2::DynReal64& strechn, const hypela2::DynReal64_2& eigvn,
const hypela2::DynReal64_2& ffn1, const hypela2::DynReal64_2& frotn1,
const hypela2::DynReal64& strechn1, const hypela2::DynReal64_2& eigvn1, const SCAInt32
ncrd,
const SCAInt32 itel, const SCAInt32 ndeg, const SCAInt32 ndm, const SCAInt32 nnode,
const SCAInt32 jtype, const hypela2::DynInt32& lclass, const SCAInt32 ifr,
const SCAInt32 ifu, const SCAInt32 nstats, const SCAInt32 isunit,
const hypela2::DynInt32& idata, const hypela2::DynReal64& rdata,
const hypela2::DynInt32& cidata)
{
return SCASuccess;
}

SCAResult Materials::usrHypela2_64(hypela2::DynReal64_2& d, hypela2::DynReal64& g, const hypela2::DynReal64& e,
const hypela2::DynReal64& de, hypela2::DynReal64& s, const hypela2::DynReal64& t,
Main Index
Utility Routines
30
const hypela2::DynReal64& dt, const SCAInt64 ngens, const hypela2::DynInt64& n,
const SCAInt64 nn, const hypela2::DynInt64& kcus, const hypela2::DynInt64& matus,
const SCAInt64 ndi, const SCAInt64 nshear, const hypela2::DynReal64_2& disp,
const hypela2::DynReal64_2& dispt, const hypela2::DynReal64_2& coord,
const hypela2::DynReal64_2& ffn, const hypela2::DynReal64_2& frotn,
const hypela2::DynReal64& strechn, const hypela2::DynReal64_2& eigvn,
const hypela2::DynReal64_2& ffn1, const hypela2::DynReal64_2& frotn1,
const hypela2::DynReal64& strechn1, const hypela2::DynReal64_2& eigvn1, const SCAInt64
ncrd,
const SCAInt64 itel, const SCAInt64 ndeg, const SCAInt64 ndm, const SCAInt64 nnode,
const SCAInt64 jtype, const hypela2::DynInt64& lclass, const SCAInt64 ifr,
const SCAInt64 ifu, const SCAInt64 nstats, const SCAInt64 isunit,
const hypela2::DynInt64& idata, const hypela2::DynReal64& rdata,
const hypela2::DynInt64& cidata)
{
return SCASuccess;
}
FORTRAN
subroutine ext_hypela2(d, g, e, de, s, t, dt, ngens, n, nn, kcus,
& matus, ndi, nshear, disp, dispt, coord, ffn, frotn,
& strechn, eigvn, ffn1, frotn1, strechn1, eigvn1, ncrd,
& itel, ndeg, ndm, nnode, jtype, lclass, ifr, ifu,
& nstats, isunit, idata, rdata, cdata,
& len_idata, len_rdata, len_cdata, error_code)
implicit none
integer, intent(in) :: ngens, nn, ndi, nshear, ncrd, itel, ndeg
integer, intent(in) :: ndm, nnode, jtype, ifr, ifu, nstats
integer, intent(in) :: isunit
integer, intent(in), dimension(2) :: n, kcus, matus
integer, intent(in), dimension(2) :: lclass
real(8), intent(out), dimension(ngens, ngens) :: d
real(8), intent(out), dimension(ngens) :: g, s
real(8), intent(in), dimension(ngens) :: e, de
real(8), intent(in), dimension(nstats) :: t, dt
real(8), intent(in), dimension(ndeg, nnode) :: disp, dispt
real(8), intent(in), dimension(ndeg, nnode) :: coord
real(8), intent(in), dimension(itel, itel) :: ffn, ffn1
real(8), intent(in), dimension(itel, itel) :: frotn, frotn1
real(8), intent(in), dimension(itel) :: strechn, strechn1
real(8), intent(in), dimension(itel, itel) :: eigvn, eigvn1
end subroutine ext_hypela2
Required Input:
E is the total elastic mechanical strain.
DE is the increment of mechanical strain.
T(1) is the temperature at t = tn
Main Index
Utility Routines
DT(1) is the increment of temperature.
NGENS is the size of the stress-strain law.
N is the element number.
NN is the integration point number.
KCUS(1) is your layer number (always 1 for continuum elements).
KCUS(2) is the internal layer number (always 1 for continuum element).
MATUS(1) is the user material identifier.
MATUS(2) is the internal material identifier.
NDI is the number of direct components.
NSHEAR is the number of shear components.
DISP is the incremental displacements.
DISPT
is the displacements at (at assembly) and the displacements at (at
stress recovery).
COORD is the coordinates.
NCRD is the number of coordinates.
NDEG is the number of degrees of freedom.
ITEL is the dimension of F and R; 2 for plane-stress and 3 for the rest of the cases.
NNODE is the number of nodes per element.
JTYPE is the element type.
LCLASS(1) is the element class.
LCLASS(2) is 0 for displacement element.
is 1 for lower-order Herrmann element.
is 2 for higher-order Herrmann element.
IFR is set to 1 if R has been calculated.
IFU is set to 1 if STRECH has been calculated.
At (or the beginning of the increment):
FFN is the deformation gradient.
FROTN is the rotation tensor.
STRECHN
is the square of principal stretch ratios, (i).
EIGVN (I,J) is the I principal direction components for J eigenvalues.
At (or the current time step):
FFN1 is the deformation gradient.
FROTN1 is the rotation tensor.
t t
n
= t t
n 1 +
=
t t
n
=
t t
n 1 +
=
Main Index
Utility Routines
32
Parameter
Without a specific parameter, engineering strain and stress are passed.
With the NLMOPTS,LRGDISP parameter, Green-Lagrange strains and second Piola-Kirchhott
stresses are passed.
With NLMOPTS,LRGSTRN parameter, logarithmic strains and Cauchy stresses are passed.
For large strain rubber elasticity, the EXT_UELASTOMER, 34 user subroutine is recommended.
For large strain inelasticity, the NLMOPTS,LRGSTRN parameter must be used. With the
parameter, strain and stress components are rotated by the program to account for rigid-body
motion before EXT_HYPELA2 is called; so, the stress integration for the co-rotational part is
performed in EXT_HYPELA2 based on rotation neutralized values. The user is required to pass
back the updated rotation neutralized stress based on the co-rotational system. The shell
thickness is only updated with the NLMOPTS,LRGSTRN parameter.
Strains
E( ) and DE( ), which are passed to EXT_HYPELA2, are the elastic mechanical strain and the increment
of mechanical strain, respectively. Here, mechanical strain is defined by total strain thermal strain.
Note that for the first iteration during assembly, DE is an estimate of the strain change.
Coordinate System
Continuum (3-D-Solid, plane strain, axisymmetric and 2-D plane stress) elements use the global
Cartesian coordinate system for the base vectors of stress and strain components. Also, membranes,
shells and beams usually use the local, element Cartesian systems. However, if the
NLMOPTS,LRGSTRN parameter is used, strain and stress components are rotated to account of rigid-
body motion before EXT_HYPELA2 is called. So, local Cartesian coordinate system is used based on
rotation-neutralized values
If a user defined orientation is used, the stress and strain components are stored in the local orientation
axis. The basis vectors rotate with the material by rotation tensor (R) and, so the stress and strain are
already stored in the rotated orientation axis before EXT_HYPELA2 is called.
Stress and Strain Components Order of Storage
The number of strain and stress components is composed of number of direct components (NDI) and
number of shear components (NSHEAR). For example, 3-D solid elements: ndi=3 and nshear=3,
STRECHN1 is the square of principal stretch ratios, lambda (i).
EIGVN1(I,J) is the I principal direction components for J eigenvalues.
Required Output:
D is the stress strain law to be formed.
G is the change in stress due to temperature effects.
S is the stress to be updated by you.
Main Index
Utility Routines
thick shells: ndi=2 and nshear=3, thin shells and membranes: ndi=2 and nshear=1, plane strain
and axisymmetric elements: ndi=3 and nshear=1, beams: ndi=1 and shear=0 to 2. The
stress and strain are first stored direct components followed by shear components. For full components,
(ndi=3, nshear=3), S(11), S(22), S(33), S(12), S(23), S(31) is the right order
to store. For Herrmann formulation of elements, the last strain component is the volumetric strain and the
last stress component is the mean pressure constant. Thus, in the Herrmann formulation, NGENS = NDI
+ NSHEAR + 1.
Tangent Stiffness
The user also needs to provide the tangent stiffness D based on the updated stress.
The rate of convergence or a nonlinear problem depends critically on the user supplied tangent stiffness
. Before using this user subroutine for large problems, it is recommended that the user check the user
subroutine with one-element problems under displacement and load control boundary conditions. The
displacement controlled boundary condition problem checks the accuracy of the stress update procedure
while the load controlled problem checks the accuracy of the tangent stiffness. A fully consistent exact
tangent stiffness provides quadratic convergence of the displacement or residual norm.
Thermal Stress Problems
For thermal stress problems, the user needs to calculate and return the change in stress due to
temperature dependent material properties.
where and are the temperatures at time t = n and t = n + 1, respectively and is strain
increment which is passed to EXT_HYPELA2.
Deformation Gradient (F), Rotation Tensor (R) and Stretch Tensor (U)
For continuum (3-D solid, plane strain, axisymmetric and 2-D plane stress) elements and membranes, the
deformation gradient and rotation tensor are passed. For those elements, principal stretch ratio and
eigenvectors are also passed to EXT_HYPELA2. Based on the information, the user can calculate stretch
tensor (U) as follows:
DO I=1,3
DO J=1,3
UN1 (I,J) = 0.D0
DO K=1,3
UN1 (I,J) = UN1 (I,J)+DSQRT
(STRETCH1(K)*EIGVN1(I,K)*EIGVN1(J,K))
ENDDO
ENDDO
ENDDO
D
i j
c Ao
i
( )
c Ac
j
( )
----------------- =
D
G
i
G
i
D
u
n 1 +
D
u
n
( )
ij
Ac ( )
j
=
u
n
u
n 1 +
Ac ( )
j
Main Index
Utility Routines
34
In this case, STRECHN1 stores the value of the squares of the stretches, and EIGVN1(I,J) stores the
I
th
eigenvector component corresponding to the J
th
eigenvalue of C, where C is the right Cauchy-Green
Tensor at .
For shells and beams, kinematic variables are not available.
EXT_UELASTOMER
Generalized Strain Energy Function
Description
This user subroutine allows definition of the users own hyperelastic models. The subroutine is activated
by MATHE along with MATUDS bulk data options and must be used with NLMOPTS,LRGSTRN,2
within the framework of updated Lagrange formulation.
In MATHE, user needs to set Model=GHEMi, where i=1,6 defining different types of hyperelastic
models.
Foam Models
For compressible foam materials, four types of strain energy functions can be defined using the
EXT_UELASTOMER user subroutine, depending on the Model field entered in MATHE:
1. Model=GHEM1: Invariant-based model
2. Model=GHEM2: Principal-stretch-based model
3. Model=GHEM3: Invariant-based model with volumetric and deviatoric split
4. Model=GHEM4: Principal-stretch-based model with volumetric and deviatoric split
, , and ( , , and ) are strain invariants (principal stretches), and and ( , , and )
are their deviatoric parts, defined by and , ; is the
determinant of the deformation gradient.
MSC Nastran uses conventional displacement elements for user-defined compressible foam models
(GHEMi, i=1,4). No volumetric constraints are taken into account. For incompressible or nearly
incompressible rubber-like materials, rubber model with MODEL=GHEM5 or GHEM6 should be used.
t n 1 + =
W W I
1
I
2
I
3
, , ( ) =
W W
1

2

3
, , ( ) =
W W
dev
I
1
I
2
, ( ) U J ( ) + =
W W
dev

1

2

3
, , ( ) U J ( ) + =
I
1
I
2
I
3

1

2

3 I
1
I
2

1

2

3
I
1
J
2 3 /
I
1
= I
2
J
4 3 /
I
2
=
i
( J
1 3 /
i
=
i 1 2 3 ) , , = J
Main Index
Utility Routines
Rubber Models
Because rubber-like materials are nearly incompressible, it is numerically more efficient to split the
energy function into a volumetric part and a deviatoric part. A mixed formulation, which treats
hydrostatic pressure as an independent variable, is used in MSC Nastran to overcome the numerical
difficulties coming from the volumetric constraints. A linear relationship between pressure and
volumetric strain is a presupposition in the mixed formulation. Therefore, requiring only the deviatoric
part of energy function needs to be defined in the user subroutine for rubber-like materials.
Invariant-based rubber models can be defined using the EXT_UELASTOMER user subroutine if the
Model field in MATHE is set to GHEM5 (Mooney type model) or GHEM6 (Ogden type model):
5. Model=GHEM5, Invariant-based model, deviatoric part only
6. Model=GHEM6:, Principal-stretch-based model, deviatoric part only
MATUDS defines the service name corresponding to the material, and the data (integer, real and
characters) used to define the material in the user subroutine. It should look like the following for
EXT_UELASTOMER application:
MATUDS,mid,MATHE,sname,UELASTOM,
,INT,
,REAL,
,CHAR,
Where mid is the material id of MATHE, and sname is the service name. Integers (real numbers,
characters) can be defined and passed into EXT_UELASTOMER with the key word INT (REAL,
CHAR).
FORMAT
IDL
module SCA {
module MDSolver {
module Obj {
module Uds {
module Materials {
W W
dev
I
1
I
2
, ( ) =
W W
dev

1

2

3
, , ( ) =
Note: If MODEL=GHEM5 or GHEM6, only the deviatoric part of the energy function is defined via
the EXT_UELASTOMER user subroutine. The volumetric part is calculated internally by
MSC Nastran. For this purpose, the bulk modulus MUST be defined with MATHE bulk
data option.
Main Index
Utility Routines
36
module uelastomer {
interface SCAIMDSolverUelastomer : SCAIService
{
SCAResult usrUelastomer_32( in SCAInt32 iflag,
in DynInt32 m,
in SCAInt32 nn,
in DynInt32 matus,
in DynReal64 be,
in SCAReal64 x1,
in SCAReal64 x2,
in SCAReal64 x3,
in SCAReal64 detft,
out SCAReal64 enerd,
out SCAReal64 w1,
out SCAReal64 w2,
out SCAReal64 w3,
out SCAReal64 w11,
out SCAReal64 w22,
out SCAReal64 w33,
out SCAReal64 w12,
out SCAReal64 w23,
out SCAReal64 w31,
out SCAReal64 dudj,
out SCAReal64 du2dj,
in DynReal64 dt,
in DynReal64 dtdl,
in SCAInt32 nstats,
in SCAInt32 isunit,
in DynInt32 idata,
in DynReal64 rdata,
SCAResult usrUelastomer_64( in SCAInt64 iflag,
in DynInt64 m,
in SCAInt64 nn,
in DynInt64 matus,
in DynReal64 be,
in SCAReal64 x1,
in SCAReal64 x2,
in SCAReal64 x3,
in SCAReal64 detft,
out SCAReal64 enerd,
out SCAReal64 w1,
out SCAReal64 w2,
out SCAReal64 w3,
out SCAReal64 w11,
out SCAReal64 w22,
out SCAReal64 w33,
out SCAReal64 w12,
Main Index
Utility Routines
out SCAReal64 w23,
out SCAReal64 w31,
out SCAReal64 dudj,
out SCAReal64 du2dj,
in DynReal64 dt,
in DynReal64 dtdl,
in SCAInt64 nstats,
in SCAInt64 isunit,
in DynInt64 idata,
in DynReal64 rdata,
};
}; // uelastomer
}; // Materials
}; // Uds
}; // Obj
}; // MDSolver
}; // SCA
C++
SCAResult Materials::usrUelastomer_32(const SCAInt32 iflag, const uelastomer::DynInt32& m, const SCAInt32 nn,
const uelastomer::DynInt32& matus, const uelastomer::DynReal64& be, const SCAReal64
x1,
const SCAReal64 x2, const SCAReal64 x3, const SCAReal64 detft, SCAReal64& enerd,
SCAReal64& w1, SCAReal64& w2, SCAReal64& w3, SCAReal64& w11, SCAReal64& w22,
SCAReal64& w33, SCAReal64& w12, SCAReal64& w23, SCAReal64& w31, SCAReal64& dudj,
SCAReal64& du2dj, const uelastomer::DynReal64& dt, const uelastomer::DynReal64&
dtdl,
const SCAInt32 nstats, const SCAInt32 isunit, const uelastomer::DynInt32& idata,
const uelastomer::DynReal64& rdata, const uelastomer::DynInt32& cidata)
{
return SCASuccess;
}

SCAResult Materials::usrUelastomer_64(const SCAInt64 iflag, const uelastomer::DynInt64& m, const SCAInt64 nn,
const uelastomer::DynInt64& matus, const uelastomer::DynReal64& be, const SCAReal64
x1,
const SCAReal64 x2, const SCAReal64 x3, const SCAReal64 detft, SCAReal64& enerd,
SCAReal64& w1, SCAReal64& w2, SCAReal64& w3, SCAReal64& w11, SCAReal64& w22,
SCAReal64& w33, SCAReal64& w12, SCAReal64& w23, SCAReal64& w31, SCAReal64& dudj,
SCAReal64& du2dj, const uelastomer::DynReal64& dt, const uelastomer::DynReal64&
dtdl,
const SCAInt64 nstats, const SCAInt64 isunit, const uelastomer::DynInt64& idata,
const uelastomer::DynReal64& rdata, const uelastomer::DynInt64& cidata)
{
return SCASuccess;
}
FORTRAN
subroutine ext_uelastomer(iflag, m, nn, matus, be, x1, x2, x3,
& detft, enerd, w1, w2, w3, w11, w22, w33, w12, w23,
& w31, dudj, du2dj, dt, dtdl, nstats, isunit,
& idata, rdata, cdata, len_idata, len_rdata,
& len_cdata, error_code)
implicit none
integer, intent(in) :: iflag, nn, nstats, isunit
real(8), intent(in) :: x1, x2, x3, detft
real(8), intent(out) :: enerd, w1, w2, w3, w11, w22, w33, w12, w23
real(8), intent(out) :: w31, dudj, du2dj
Main Index
Utility Routines
38
integer, intent(in), dimension(2) :: m, matus
real(8), intent(in), dimension(6) :: be
real(8), intent(in), dimension(nstats) :: dt, dtdl
end subroutine ext_uelastomer
Input:
IFLAG Hyperelastic mode to be defined:
= 1 Foam model with energy function in terms of invariants (GHEM1)
= 2 Foam model with energy function in terms of principal stretches (GHEM2)
= 3 Foam model with energy function in terms of invariants with deviatoric split
(GHEM3)
= 4 Foam model with energy function in terms of principal stretches with deviatoric
split (GHEM4)
= 5 Rubber model with energy function in terms of invariants deviatoric part only
(GHEM5). The bulk modulus MUST be defined with MATHE.
= 6 Rubber model with energy function in terms of principal stretches deviatoric part
only (GHEM6). The bulk modulus MUST be defined with MATHE.
M(1) user element number
M(2) internal element number
NN integration point number
MATS(1) user material identification number
MATS(2) internal material identification number
BE left Cauchy-Green deformation tensor
X1,X2,X3 if iflag=1: invariants of be
if iflag=2: principal stretches
if iflag=3: deviatoric part of invariants of be
if iflag=4: deviatoric principal stretches
if iflag=5: deviatoric part of invariants of be
Main Index
Utility Routines
if iflag=6: deviatoric principal stretches
DETFT determinate of deformation gradient
DT
array of state variables (temperature at first) at
DTDL incremental state variables
Output:
ENERD
energy density at
t
n
t
n 1 +
Main Index
Utility Routines
40

Example:
To define a rubber material based on strain energy function (Mooney model):
W = C
1
(I
1
-3) + C
2
(I
2
-3)
Foam Rubber
iflag = 1 iflag = 2 iflag = 3 iflag = 4 iflag =5 iflag =6
W1
W2
W3
N/A N/A
W11
W22
W33
N/A N/A
W12
W23
N/A N/A
W31
N/A N/A
dudj
N/A N/A N/A N/A
du2dj
N/A N/A N/A N/A
cW
cI
1
--------
cW
c
1
---------
cW
cI
1
--------
cW
c
1
---------
cW
cI
1
--------
cW
c
1
---------
cW
cI
2
--------
cW
c
2
---------
cW
cI
2
--------
cW
c
2
---------
cW
cI
2
--------
cW
c
2
---------
cW
cI
3
--------
cW
c
3
---------
cW
c
3
---------
cW
c
3
---------
c
2
W
cI
1
2
-----------
c
2
W
c
1
2
-----------
c
2
W
cI
1
2
-----------
c
2
W
c
1
2
-----------
c
2
W
cI
1
2
-----------
c
2
W
c
1
2
-----------
c
2
W
cI
2
2
-----------
c
2
W
c
2
2
-----------
c
2
W
cI
2
2
-----------
c
2
W
c
2
2
-----------
c
2
W
cI
2
2
-----------
c
2
W
c
2
2
-----------
c
2
W
cI
3
2
-----------
c
2
W
c
3
2
-----------
c
2
W
c
3
2
-----------
c
2
W
c
3
2
-----------
c
2
W
cI
1
cI
2
----------------
c
2
W
c
1
c
2
-------------------
c
2
W
cI
1
cI
2
----------------
c
2
W
c
1
c
2
-------------------
c
2
W
cI
1
cI
2
----------------
c
2
W
c
1
c
2
-------------------
c
2
W
cI
2
cI
3
----------------
c
2
W
c
2
c
3
-------------------
c
2
W
c
2
c
3
-------------------
c
2
W
c
2
c
3
-------------------
c
2
W
cI
3
cI
1
----------------
c
2
W
c
3
c
1
-------------------
c
2
W
c
3
c
1
-------------------
c
2
W
c
3
c
1
-------------------
cU
cJ
-------
cU
cJ
-------
c
2
U
cJ
2
----------
c
2
U
cJ
2
----------
Main Index
Utility Routines
with a bulk modulus K, the input file should have MATHE and MATUDS look like the following:
MATHE,2,GHEM5,,K,
MATUDS,2,MATHE,Sname,UELASTOM,
,REAL, C
1
,C
2

where:
Sname is the material service name.
The code inserted in EXT_UELASTOMER should be the following:
W1=RDATA(1)
W2=RDATA(2)
ENERD=RDARA(1) *(X1-3.d0) + RDATA(2) *(X2-3.d0)
EXT_ORIENT
Specification of Preferred Orientation
Description
The EXT_ORIENT user subroutine is used to supply a preferred orientation so that anisotropic material
constants can be defined in this orientation. This user subroutine can be activated by anisotropic material
definition options, and/or the MATUSR option, along with MATUDS option.
characters) used to define the material properties in the user subroutine. It should look like the following
for EXT_ORIENT application:
MATUDS,mid,matopt,sname,ORIENT,
,INT,
,REAL,
,CHAR,
Where matopt is the material bulk data option such as MAT2, MAT8 or MATORT; mid is the material
identification number consistent with the corresponding matopts; and sname is the name of this service.
Integers (real numbers, characters) can be defined and passed into EXT_ORIENT with the key word INT
(REAL, CHAR).
Format
IDL
module SCA {
module MDSolver {
module Obj {
Main Index
Utility Routines
42
module Uds {
module Materials {
module orient {
typedef SCAInt32 DynInt32_2[][];
interface SCAIMDSolverOrient : SCAIService
{
SCAResult usrOrient_32( in DynInt32 n,
in SCAInt32 nn,
in DynInt32 kcus,
out DynReal64_2 g,
in DynInt32 matus,
in SCAInt32 isunit,
in DynReal64 xipt,
in SCAInt32 ncrd,
in DynInt32 idata,
in DynReal64 rdata,
in DynInt32 cidata);
SCAResult usrOrient_64( in DynInt64 n,
in SCAInt64 nn,
in DynInt64 kcus,
out DynReal64_2 g,
in DynInt64 matus,
in SCAInt64 isunit,
in DynReal64 xipt,
in SCAInt64 ncrd,
in DynInt64 idata,
in DynReal64 rdata,
};
}; // orient
}; // Materials
}; // Uds
}; // Obj
}; // MDSolver
}; // SCA
C++
SCAResult Materials::usrOrient_32(const orient::DynInt32& n, const SCAInt32 nn, const orient::DynInt32& kcus,
orient::DynReal64_2& g, const orient::DynInt32& matus, const SCAInt32 isunit,
const orient::DynReal64& xipt, const SCAInt32 ncrd, const orient::DynInt32& idata,
const orient::DynReal64& rdata, const orient::DynInt32& cidata)
{
return SCASuccess;
}
SCAResult Materials::usrOrient_64(const orient::DynInt64& n, const SCAInt64 nn, const orient::DynInt64& kcus,
Main Index
Utility Routines
orient::DynReal64_2& g, const orient::DynInt64& matus, const SCAInt64 isunit,
const orient::DynReal64& xipt, const SCAInt64 ncrd, const orient::DynInt64& idata,
const orient::DynReal64& rdata, const orient::DynInt64& cidata)
{
return SCASuccess;
}
FORTRAN
subroutine ext_orient(n, nn, kcus, g, matus, isunit, xipt, ncrd,
implicit none
integer, intent(in) :: nn, isunit, ncrd
integer, intent(in), dimension(2) :: n, kcus, matus
real(8), intent(out), dimension(3, 3) :: g
real(8), intent(in), dimension(ncrd) :: xipt
end subroutine ext_orient

All parameters except G are passed in by the program the user must supply the G matrix. G is the
transformation to the preferred orientation from the usual program orientation:
where:
Required Input:
N(1) is the user element number.
N(2) is the internal element number.
Required Output:
G is the transformation matrix to be defined here.
v'
1
v'
2
v'
3
)

`

G
11
G
12
G
13
G
21
G
22
G
23
G
31
G
32
G
33
v
1
v
2
v
3
)

`

=
Main Index
Utility Routines
44
For curvilinear systems, G is defined by G(I,J) = . For planar transformations, G(3,I) = G(I,3)
= 0; G(3,3) = 1.0; I = 1,2 must be given.
EXT_CRPLAW
Input of Special Creep Law
Description
The EXT_CRPLAW user subroutine allows the user to specify the increment of creep strain.
The use of such a user subroutine is flagged through bulk data option MATUDS. This user subroutine is
called as required during the analysis because of possible re-cycling due to nonconvergence. The number
of times the user subroutine is called in each increment is not fixed.
characters) used to define the material properties in the user subroutine. It should look like the following
for EXT_CRPLAW application:
MATUDS,mid,matopt,sname,CRPLAW,
,INT,
,REAL,
,CHAR,
Where matopt is the material bulk data option such as MAT1 or MATVP; mid is the material
identification number consistent with the corresponding matopts; and sname is the name of this service.
Integers (real numbers, characters) can be defined and passed into EXT_CRPLAW with the key word
INT (REAL, CHAR).
MSC Nastran allows the user to input his own creep law through the EXT_CRPLAW user subroutine. The
assumed form of the law is:
where:
v is the vector in the program system.
v' is the vector in the preferred system.
Note: This user subroutine should not be used if the user desires that the material orientation
be a design variable. Use,, that is, PCOMP option instead.
g
j
i
c
c
f o T t c
c
p o
1
o
2
et c , , , , , , , ( ) =
Main Index
Utility Routines
Format
IDL
module SCA {
module MDSolver {
module Obj {
module Uds {
module Materials {
module crplaw {
interface SCAIMDSolverCrplaw : SCAIService
{
SCAResult usrCrplaw_32( in SCAReal64 eqcp,
out SCAReal64 eqcpnc,
in DynReal64 s,
in DynReal64 crpe,
in DynReal64 t,
in DynReal64 dt,
in SCAReal64 timinc,
in SCAReal64 cptim,
in SCAInt32 m,
in SCAInt32 nn,
in DynInt32 kcus,
in DynInt32 matus,
in SCAInt32 ndi,
in SCAInt32 nshear,
in SCAInt32 nstats,
in SCAInt32 isunit,
is the equivalent creep strain rate, in uniaxial tension.
is the current equivalent (J) stress, normalized for uniaxial tension.
T is the current total temperature.
t is the current total time.
is the current total equivalent creep strain, normalized for uniaxial tension.
p is the hydrostatic stress.
are the state variables. MSC Nastran requires the user to program his creep law so that an
equivalent creep strain increment is defined.
c
c
o
c
c
o
1
o
2
etc. , ,
Main Index
Utility Routines
46
in DynInt32 idata,
in DynReal64 rdata,
SCAResult usrCrplaw_64( in SCAReal64 eqcp,
out SCAReal64 eqcpnc,
in DynReal64 s,
in DynReal64 crpe,
in DynReal64 t,
in DynReal64 dt,
in SCAReal64 timinc,
in SCAReal64 cptim,
in SCAInt64 m,
in SCAInt64 nn,
in DynInt64 kcus,
in DynInt64 matus,
in SCAInt64 ndi,
in SCAInt64 nshear,
in SCAInt64 nstats,
in SCAInt64 isunit,
in DynInt64 idata,
in DynReal64 rdata,
};
}; // crplaw
}; // Materials
}; // Uds
}; // Obj
}; // MDSolver
}; // SCA
C++
SCAResult Materials::usrCrplaw_32(const SCAReal64 eqcp, SCAReal64& eqcpnc, const crplaw::DynReal64& s,
const crplaw::DynReal64& crpe, const crplaw::DynReal64& t, const crplaw::DynReal64&
dt,
const SCAReal64 timinc, const SCAReal64 cptim, const SCAInt32 m, const SCAInt32 nn,
const crplaw::DynInt32& kcus, const crplaw::DynInt32& matus, const SCAInt32 ndi,
const SCAInt32 nshear, const SCAInt32 nstats, const SCAInt32 isunit,
const crplaw::DynInt32& idata, const crplaw::DynReal64& rdata, const
crplaw::DynInt32& cidata)
{
return SCASuccess;
}

SCAResult Materials::usrCrplaw_64(const SCAReal64 eqcp, SCAReal64& eqcpnc, const crplaw::DynReal64& s,
const crplaw::DynReal64& crpe, const crplaw::DynReal64& t, const crplaw::DynReal64&
dt,
const SCAReal64 timinc, const SCAReal64 cptim, const SCAInt64 m, const SCAInt64 nn,
const crplaw::DynInt64& kcus, const crplaw::DynInt64& matus, const SCAInt64 ndi,
const SCAInt64 nshear, const SCAInt64 nstats, const SCAInt64 isunit,
const crplaw::DynInt64& idata, const crplaw::DynReal64& rdata, const
crplaw::DynInt64& cidata)
{
return SCASuccess;
}
FORTRAN
subroutine ext_crplaw(eqcp, eqcpnc, s, crpe, t, dt, dtdl, timinc,
& cptim, m, nn, kcus, matus, ndi, nshear, nstats,
& ncomp, isunit, idata, rdata, cdata, len_idata,
& len_rdata, len_cdata, error_code)
Main Index
Utility Routines
implicit none
integer, intent(in) :: m, nn, ndi, nshear, nstats, ncomp, isunit
real(8), intent(in) :: eqcp, timinc, cptim
real(8), intent(out) :: eqcpnc
integer, intent(in), dimension(2) :: kcus, matus
real(8), intent(in), dimension(ncomp) :: s, crpe
real(8), intent(in), dimension(3) :: t
end subroutine ext_crplaw
Main Index
Utility Routines
48
The simplest way to define a creep strain increment from a given rate law is to multiply by
At, the time increment:
Example:
We wish to use the creep law (where A=1.23e-10 and B=4.5) for material 2 defined by MAT1 and
MATVP:
Required Input:
EQCP Passed in as total equivalent creep strain.
STR is the stress array.
CRPE is the incremental creep strain array. If you want to define a creep strain law not
following the normality condition, the creep strain increment can be defined here.
T(1) is the current total equivalent (J
2
) stress.
T(2) is the current total hydrostatic stress.
DT(1) is the current total temperature.
TIMINC is the current time increment.
CPTIM is the current total time.
M is the current element number.
MATUS(1) is the user material id.
NDI is the number of direct components of strain.
NSHEAR is the number of shear components of strain.
Required Output:
EQCPNC
is the equivalent creep strain increment; to be defined by the user in this user
subroutine.
Must be redefined by the user as equivalent creep strain increment.
c
c
E
2
3
--- Ac
c
i j
Ac
c
ij
\ .
| |
1 2
=
c
c
f o et c , ( ) =
Ac
c
At f o et c , ( ) =
Main Index
Utility Routines
The input would like:
MATVP,2,0
MATUDS,2,MAT1,sname,CRPLAW,
,REAL,1.23e-10,4.5,
Where sname is the name of this service.
The user code would be programmed as follows:
EXT_UFAIL
User-defined Failure Criterion
Description
The EXT_UFAIL user subroutine is provided to allow the user to calculate his own scalar failure criterion.
To call the EXT_UFAIL user subroutine, the user must specify user failure criterion type in MATF option,
and define proper service and user subroutine name in MATUDS option. EXT_UFAIL is then called for
every integration point associated with the material id specified in both MATF and MATUDS.
characters) used to define the failure criterion in the user subroutine. It should look like the following for
EXT_UFAIL application:
MATUDS,mid,MATF,sname,UFAIL,
,INT,
,REAL,
C OBTAIN SINH (T/B)
S = T(1)
IF (S.EQ.0.) GO TO 1
SINHT = .5*(EXP(S/rdata(2))-EXP(-S/rdata(2)))
GO TO 2
1 SINHT = 0.
2 CONTINUE
C DEFINE EQCPNC
EQCPNC = TIMINC*rdata(1)*SINHT
c
c
A
o
B
---
\ .
| |
sinh =
Main Index
Utility Routines
50
,CHAR,
Where mid is the material identification number consistent with the corresponding MATF; sname is the
name of this service. Integers (real numbers, characters) can be defined and passed into EXT_UFAIL
with the key word INT (REAL, CHAR).
This routine may be used with all elastic-plastic materials. Progressive cracking is only available with
the additive elastic-plastic model.
Format
IDL
C++
SCAResult Materials::usrUfail_32(const SCAInt32 nelem, const SCAInt32 nint, const ufail::DynInt32& kcus,
const ufail::DynInt32& matus, const ufail::DynReal64& stress, const ufail::DynReal64&
strain,
const SCAInt32 ndi, const SCAInt32 nshear, ufail::DynReal64& failc, const
ufail::DynReal64& dt,
const ufail::DynReal64& dtdl, const SCAInt32 nstats, const SCAInt32 isunit,
const ufail::DynInt32& idata, const ufail::DynReal64& rdata, const ufail::DynInt32&
cidata)
{
return SCASuccess;
}

SCAResult Materials::usrUfail_64(const SCAInt64 nelem, const SCAInt64 nint, const ufail::DynInt64& kcus,
const ufail::DynInt64& matus, const ufail::DynReal64& stress, const ufail::DynReal64&
strain,
const SCAInt64 ndi, const SCAInt64 nshear, ufail::DynReal64& failc, const
ufail::DynReal64& dt,
const ufail::DynReal64& dtdl, const SCAInt64 nstats, const SCAInt64 isunit,
const ufail::DynInt64& idata, const ufail::DynReal64& rdata, const ufail::DynInt64&
cidata)
{
return SCASuccess;
}
FORTRAN
User subroutine EXT_UFAIL is written with the following headers:
subroutine ext_ufail(nelem, nint, kcus, matus, stress, strain,
& ndi, nshear, failc, dt, dtdl, nstats, ncomp, isunit,
implicit none
integer, intent(in) :: nelem, nint, ndi, nshear, nstats, isunit
integer, intent(in) :: ncomp
real(8), intent(in), dimension(ncomp) :: stress, strain
real(8), intent(out), dimension(2) :: failc
end subroutine ext_ufail
Main Index
Utility Routines
EXT_UPROGFAIL
Definition of Material Stiffness Reduction Factors for Progressive Failure Analysis
Description
This user subroutine allows users to define the stiffness reduction factors for a progressive failure
analysis.
The routine is called for an element integration point whenever failure occurs. The failure criteria can be
defined on the MATF option, or via the EXT_UFAIL user subroutine.
For this routine to be invoked, the progressive failure type (the field ITYPE in MATF bulk data option)
must be either gradual selective or immediate selective stiffness degradation.
MATUDS should be used together with MATF to activate EXT_UPROGFAIL. MATUDS defines the
service name corresponding to the material, and the data (integer, real and characters) used to define the
stiffness reduction factors in the user subroutine. It should look like the following for EXT_UPROGFAIL
application:
MATUDS,mid,MATF,sname,UPROGFAIL,
,INT,
Required Input:
N(1) is the user element number.
N(2) is the internal element number.
MATUS(1) is the user material identifier.
STRESS is the current total stress state.
STRAIN is the current total strain.
NDI is the number of direct stresses.
NSHEAR is the number of shear stresses.
Required Output:
FAILCR (1) is user-defined failure criteria.
FAILCR (2) is user-defined strength ratio (allowable stress/actual stress)
Main Index
Utility Routines
52
,REAL,
,CHAR,
Where mid is the material identification number consistent with the corresponding MATF; sname is the
name of this service. Integers (real numbers, characters) can be defined and passed into
EXT_UPROGFAIL with the key word INT (REAL, CHAR).
Format
IDL
module SCA {
module MDSolver {
module Obj {
module Uds {
module Materials {
module uprogfail {
interface SCAIMDSolverUprogfail : SCAIService
{
SCAResult usrUprogfail_32( in SCAInt32 nelem,
in SCAInt32 nint,
in DynInt32 kcus,
in DynInt32 matus,
in DynReal64 stress,
in DynReal64 strain,
in SCAInt32 icrit,
in DynReal64 fi,
in DynReal64 redfac0,
out DynReal64 redfac,
out SCAInt32 ideact,
in DynReal64 dt,
in DynReal64 dtdl,
in SCAReal64 time,
in SCAReal64 timeinc,
in SCAInt32 nstats,
in SCAInt32 isunit,
in DynInt32 idata,
in DynReal64 rdata,
SCAResult usrUprogfail_64( in SCAInt64 nelem,
in SCAInt64 nint,
Main Index
Utility Routines
in DynInt64 kcus,
in DynInt64 matus,
in DynReal64 stress,
in DynReal64 strain,
in SCAInt64 icrit,
in DynReal64 fi,
in DynReal64 redfac0,
out DynReal64 redfac,
out SCAInt64 ideact,
in DynReal64 dt,
in DynReal64 dtdl,
in SCAReal64 time,
in SCAReal64 timeinc,
in SCAInt64 nstats,
in SCAInt64 isunit,
in DynInt64 idata,
in DynReal64 rdata,
};
}; // uprogfail
}; // Materials
}; // Uds
}; // Obj
}; // MDSolver
}; // SCA
C++
SCAResult Materials::usrUprogfail_32(const SCAInt32 nelem, const SCAInt32 nint, const uprogfail::DynInt32& kcus,
const uprogfail::DynInt32& matus, const uprogfail::DynReal64& stress,
const uprogfail::DynReal64& strain, const SCAInt32 icrit, const uprogfail::DynReal64&
fi,
const uprogfail::DynReal64& redfac0, uprogfail::DynReal64& redfac, SCAInt32& ideact,
const uprogfail::DynReal64& dt, const uprogfail::DynReal64& dtdl, const SCAReal64
time,
const SCAReal64 timeinc, const SCAInt32 nstats, const SCAInt32 isunit,
const uprogfail::DynInt32& idata, const uprogfail::DynReal64& rdata,
const uprogfail::DynInt32& cidata)
{
return SCASuccess;
}

SCAResult Materials::usrUprogfail_64(const SCAInt64 nelem, const SCAInt64 nint, const uprogfail::DynInt64& kcus,
const uprogfail::DynInt64& matus, const uprogfail::DynReal64& stress,
const uprogfail::DynReal64& strain, const SCAInt64 icrit, const uprogfail::DynReal64&
fi,
const uprogfail::DynReal64& redfac0, uprogfail::DynReal64& redfac, SCAInt64& ideact,
const uprogfail::DynReal64& dt, const uprogfail::DynReal64& dtdl, const SCAReal64
time,
const SCAReal64 timeinc, const SCAInt64 nstats, const SCAInt64 isunit,
const uprogfail::DynInt64& idata, const uprogfail::DynReal64& rdata,
const uprogfail::DynInt64& cidata)
{
return SCASuccess;
}
FORTRAN
subroutine ext_uprogfail(nelem, nint, kcus, matus, stress, strain,
& icrit, fi, redfac0, redfac, ideact, dt, dtdl, time,
& timeinc, nstats, ncomp, isunit, idata, rdata, cdata,
& len_idata, len_rdata, len_cdata, error_code)
implicit none
integer, intent(in) :: nelem, nint, icrit, nstats, isunit, ncomp
Main Index
Utility Routines
54
integer, intent(out) :: ideact, error_code
real(8), intent(in) :: time, timeinc
real(8), intent(in), dimension(ncomp) :: stress, strain
real(8), intent(in), dimension(6) :: fi, redfac0
real(8), intent(out), dimension(6) :: redfac
end subroutine ext_uprogfail
Required Input:
NELEM is the user element number
NINT is the integration point number
KCUS is the layer number
kcus(1) user layer number
kcus(2) internal layer number
MATUS is the material ID
matus(1) user material ID
matus(2) internal material ID
STRESS is the current total stresses in preferred system,
in full tensor format ( , , , , , )
STRAIN is the current total strains in preferred system,
in full tensor format ( , , , , , )
ICRIT is the current failure criterion:
1 maximum stress
2 maximum strain
3 Tsai-Wu
4 Hoffman
5 Hill
6 not used
7 user
8 Hashin
o
11
o
22
o
33
o
12
o
23
o
13
c
11
c
22
c
33
c
12
c
23
c
13
Main Index
Utility Routines
The six components of redfac will be used for scaling the material moduli of an orthotropic material
according to
The Poissons ratios are scaled the same way as the corresponding shear modulus.
For an isotropic material, the Youngs modulus is scaled with the smallest of the components of redfac
and the shear modulus is calculated using the updated Youngs modulus and the Poissons ratio.
9 Hashin Fabric
10 not used
11 not used
12 Hashin Tape
13 puck
FI is the array of current failure indices
REDFAC0 is the array of current reduction factors
REDFAC is the array of reduction factors to be updated.
upon entry it contains the values calculated by the program.
IDEACT is the deactivation flag. Set to 1 to flag that the element should be deactivated. If all
integration points of the element have this flag set, it is deactivated at the end of the
current increment. Upon entry, it contains the value calculated by the program.
DT is the array of state variables at the beginning of the current increment;
dt(1) is the temperature
DTDL is the array of increment of state variables;
dtdl(1) is the incremental temperature.
TIME is the time at the beginning of the current increment
TIMEINC is the time increment
E
11
new
re df ac 1 ( ) E
11
orig
=
E
22
new
re df ac 2 ( ) E
22
orig
=
E
33
new
re df ac 3 ( ) E
33
orig
=
G
12
new
re df ac 4 ( ) G
12
orig
=
G
23
new
re df ac 5 ( ) G
23
orig
=
G
31
new
re df ac 6 ( ) G
31
orig
=
Main Index
Utility Routines
56
The case of general anisotropy is not supported.
EXT_MOTION
Definition of Rigid Surface Motion for 3-D Contact (
Description
This user subroutine allows the definition of non-uniform rigid surface motions in conjunction with
contact analysis. Its call is triggered by the BCONUDS bulk data option. This user subroutine should only
be used with velocity controlled rigid surfaces.
The EXT_MOTION user subroutine is called during the calculations at the beginning of each time
increment and the users return surface velocities for that increment. Imposed displacement increments
at nodal points in contact with rigid surfaces are obtained from the velocity multiplied by the time
increment. The surface path becomes an explicit forward integration of velocities. Therefore, caution
should be taken when there are abrupt changes in surface path direction or abrupt changes in velocity by
making time increments as small as necessary.
If, at the start of the analysis, a rigid surface is placed apart from the deformable body, the EXT_MOTION
user subroutine is also used in the approaching phase.
BCONUDS activates the call to contact related user subroutines such as EXT_MOTION, and defines the
data (integer, real and characters) required in the user subroutine. It should look like the following for
EXT_MOTION application:
BCONUDS,bid,BCBODY,sname,MOTION,
,INT,
,REAL,
,CHAR,
Caution: Please note that if the coordinates of the center of rotation are defined unconditionally in
this routine, they will be set to that same value for all increments of the analysis, causing
the rigid surface to rotate around a fixed point in space. On the other hand, if the position
of the center of rotation is defined only once in increment 0, as in
if(inc.eq.0) then
x(1)=...
etc.
endif
the center of the rotation is updated internally as motion and deformation take place.
Obviously, the results will be different for the two cases.
Main Index
Utility Routines
Where bid is the contact body identification number consistent with the corresponding BCBODY; and
sname is the name of this service. Integers (real numbers, characters) can be defined and passed into
EXT_MOTION with the key word INT (REAL, CHAR).
Format
IDL
module SCA {
module MDSolver {
module Obj {
module Uds {
module Contact {
module motion {
interface SCAIMDSolverMotion : SCAIService
{
SCAResult usrMotion_32( in DynReal64 x,
in DynReal64 f,
out DynReal64 v,
in SCAReal64 time,
in SCAReal64 dtime,
in SCAInt32 nsurf,
in SCAInt32 inc,
in SCAInt32 isunit,
in DynInt32 idata,
in DynReal64 rdata,
SCAResult usrMotion_64( in DynReal64 x,
in DynReal64 f,
out DynReal64 v,
in SCAReal64 time,
in SCAReal64 dtime,
in SCAInt64 nsurf,
in SCAInt64 inc,
in SCAInt64 isunit,
in DynInt64 idata,
in DynReal64 rdata,
};
}; // motion
}; // Contact
}; // UDS
}; // Obj
}; // MDSolver
}; // SCA
Main Index
Utility Routines
58
C++
SCAResult Contact::usrMotion_32(const motion::DynReal64& x, const motion::DynReal64& f, motion::DynReal64& v,
const SCAReal64 time, const SCAReal64 dtime, const SCAInt32 nsurf, const SCAInt32 inc,
const SCAInt32 isunit, const motion::DynInt32& idata, const motion::DynReal64& rdata,
const motion::DynInt32& cidata)
{
return SCASuccess;
}

SCAResult Contact::usrMotion_64(const motion::DynReal64& x, const motion::DynReal64& f, motion::DynReal64& v,
const SCAReal64 time, const SCAReal64 dtime, const SCAInt64 nsurf, const SCAInt64 inc,
const SCAInt64 isunit, const motion::DynInt64& idata, const motion::DynReal64& rdata,
const motion::DynInt64& cidata)
{
return SCASuccess;
}
FORTRAN
subroutine ext_motion(x, f, v, time, dtime, nsurf, inc, isunit,
& nsize, nsize_v, idata, rdata, cdata, len_idata,
implicit none
integer, intent(in) :: nsurf, inc, isunit, nsize, nsize_v
real(8), intent(in) :: time, dtime
real(8), intent(in), dimension(nsize) :: x, f
real(8), intent(out), dimension(nsize_v) :: v

! uncomment to call existing implementation
! call motion(x, f, v, time, dtime, nsurf, inc)
end subroutine ext_motion
Required Input:
X(6) is the array of current die defining coordinates.
X(1) = first coordinate of center of rotation.
X(2) = second coordinate of center of rotation.
X(3) = third coordinate of center of rotation.
Axis for specifying angular velocity:
X(4) = first component of direction cosine.
X(5) = second component of direction cosine.
X(6) = third component of direction cosine.
F(6) is the array of current surface loads.
F(1) = first component of load.
Main Index
Utility Routines
Example
Assume that a rigid surface is identified as surface number 2 and is moving in the negative x-direction
with a velocity of 1.0.
The input for BCONUDS should be
BCONUDS,2,BCBODY,sname,MOTION,
,REAL,-1.0,
Where sname is the name of this service.
The user code for EXT_MOTION user subroutine can be written as follows:
F(2) = second component of load.
F(3) = third component of load.
F(4) = first component of moment.
F(5) = second component of moment.
F(6) = third component of moment.
TIME is the time at which data is requested.
DTIME is the current time increment.
NSURF is the surface number for which data is requested.
INC is the increment number.
Required Output:
V(4) is the array of current surface velocities.
V(1) = first component of the velocity at the center of rotation.
V(2) = second component of the velocity at the center of rotation.
V(3) = third component of the velocity at the center of radiation.
V(4) = angular velocity around axis defined above with X(4), X(5), and
X(6).
IF(NSURF.eq.2) THEN
V(1)=rdata(1)
V(2)=0.
V(3)=0.
V(4)=0.0
Main Index
Utility Routines
60
EXT_UFRIC
Definition of Friction Coefficients
Description
With this user subroutine, the user can define the variable friction coefficients or friction factors in
conjunction with contact analysis. Its call is triggered by BCONUDS option.
For distributed based friction, the EXT_UFRIC user subroutine is called for every element containing
nodes that are in contact with surfaces at the nodes. These calls are made every iteration both during the
assembly phase and during the stress recovery phase.
BCONUDS activates the call to contact related user subroutines such as EXT_UFRIC, and defines the
EXT_UFRIC application:
BCONUDS,bid,BCBODY,sname,UFRIC,
,INT,
,REAL,
,CHAR,
EXT_UFRIC with the key word INT (REAL, CHAR).
Format
IDL
module SCA {
module MDSolver {
module Obj {
module Uds {
module Contact {
module ufric {
interface SCAIMDSolverUfric : SCAIService
{
SCAResult usrUfric_32( in DynInt32 mibody,
in DynReal64 x,
ENDIF
Main Index
Utility Routines
in SCAReal64 fn,
in DynReal64 vrel,
in SCAReal64 temp,
in SCAReal64 yiel,
out SCAReal64 fric,
in SCAReal64 time,
in SCAInt32 inc,
in SCAInt32 i2or3,
in SCAInt32 nsurf,
in SCAInt32 isunit,
in DynInt32 idata,
in DynReal64 rdata,
SCAResult usrUfric_64( in DynInt64 mibody,
in DynReal64 x,
in SCAReal64 fn,
in DynReal64 vrel,
in SCAReal64 temp,
in SCAReal64 yiel,
out SCAReal64 fric,
in SCAReal64 time,
in SCAInt64 inc,
in SCAInt64 i2or3,
in SCAInt64 nsurf,
in SCAInt64 isunit,
in DynInt64 idata,
in DynReal64 rdata,
};
}; // ufric
}; // Contact
}; // UDS
}; // Obj
}; // MDSolver
}; // SCA
C++
SCAResult Contact::usrUfric_32(const ufric::DynInt32& mibody, const ufric::DynReal64& x, const SCAReal64 fn,
const ufric::DynReal64& vrel, const SCAReal64 temp, const SCAReal64 yiel, SCAReal64&
fric,
const SCAReal64 time, const SCAInt32 inc, const SCAInt32 nsurf, const SCAInt32 i2or3,
const SCAInt32 isunit, const ufric::DynInt32& idata, const ufric::DynReal64& rdata,
const ufric::DynInt32& cidata)
{
return SCASuccess;
}

SCAResult Contact::usrUfric_64(const ufric::DynInt64& mibody, const ufric::DynReal64& x, const SCAReal64 fn,
const ufric::DynReal64& vrel, const SCAReal64 temp, const SCAReal64 yiel, SCAReal64&
fric,
const SCAReal64 time, const SCAInt64 inc, const SCAInt64 nsurf, const SCAInt64 i2or3,
const SCAInt64 isunit, const ufric::DynInt64& idata, const ufric::DynReal64& rdata,
const ufric::DynInt64& cidata)
{
return SCASuccess;
}
FORTRAN
subroutine ext_ufric(mibody, x, fn, vrel, temp, yiel, fric, time,
& inc, nsurf, i2or3, isunit, idata, rdata, cdata,
Main Index
Utility Routines
62
& len_vrel, len_idata, len_rdata, len_cdata,
& error_code)
implicit none
integer, intent(in) :: inc, nsurf, i2or3, isunit, len_vrel
real(8), intent(in) :: fn, temp, yiel, time
real(8), intent(out) :: fric
integer, intent(in), dimension(4) :: mibody
real(8), intent(in), dimension(i2or3) :: x
real(8), intent(out), dimension(len_vrel) :: vrel
! call ufric(mibody,x,fn,vrel,temp,yiel,fric,time,inc,nsurf)
end subroutine ext_ufric
Required Input:
For distributed friction based on nodal stresses:
MIBODY(1) is the user element number.
MIBODY(2) is the side number.
MIBODY(3) is the surface integration point number.
MIBODY(4) is the internal element number.
For nodal friction based on nodal forces:
MIBODY(1) is the user node number.
MIBODY(2) is not used; enter 0.
MIBODY(3) is not used; enter 0.
MIBODY(4) is the internal node number.
X is the updated coordinates of contact point where friction is being calculated. The
third coordinate is zero for 2-D models.
FN is the normal stress/force being applied at that point.
VREL(1) is the relative sliding velocity at contact point for 2-D models.
VREL(1) is the sliding velocity in the first tangential direction for 3-D models.
VREL(2) is the sliding velocity in the second tangential direction for 3-D models.
TEMP(1) is the temperature of contact point.
Main Index
Utility Routines
EXT_SEPFOR
Definition of Separation Force
Description
This user subroutine allows the definition of the separation force in contact analysis. The separation
forces, FNORM and FTANG, are either calculated by the program or entered through the BCTABLE or
BCPARA option, and then passed into this user subroutine. The user decides whether these values at the
current increment are appropriate to determine whether separation occurs.
FNORM is the normal reaction force above which a node in contact separates from a surface. Any
compressive or negative value indicates real contact while a positive reaction force indicates a tendency
to separate. The default is taken as the maximum value of the residual force in the structure for the current
increment. This value can be reset by the user through the input format. Defining a too small value can
result in an increased number of iterations. Defining a very large value eliminates the possibility of
separation. FTANG is the tangential force used to determine whether a nodal point positioned at a convex
corner of surface should be sliding from patch to patch or remaining on its current patch. The default
value is half of FNORM. These two default reaction forces vary from increment to increment.
BCONUDS activates the call to contact related user subroutines such as EXT_SEPFOR, and defines the
EXT_SEPFOR application:
BCONUDS,bid,BCBODY,sname,SEPFOR,
,INT,
,REAL,
,CHAR,
EXT_SEPFOR with the key word INT (REAL, CHAR).
TEMP(2) is the voltage of contact point (Joule heating).
YIEL is the flow stress of workpiece material at contact point.
TIME is the current time.
INC is the increment number.
NSURF is the surface being contacted by the side for which friction calculations are being
made.
Required Output:
FRIC is the friction coefficient or friction factor to be provided by the user.
Main Index
Utility Routines
64
Format
IDL
module SCA {
module MDSolver {
module Obj {
module Uds {
module Contact {
module sepfor {
interface SCAIMDSolverSepfor : SCAIService
{
SCAResult usrSepfor_32( out SCAReal64 fnorm,
out SCAReal64 ftang,
in SCAInt32 ibody,
in SCAInt32 nnode,
in SCAInt32 inc,
in SCAReal64 time,
in SCAReal64 dtime,
in SCAInt32 isunit,
in DynInt32 idata,
in DynReal64 rdata,
SCAResult usrSepfor_64( out SCAReal64 fnorm,
out SCAReal64 ftang,
in SCAInt64 ibody,
in SCAInt64 nnode,
in SCAInt64 inc,
in SCAReal64 time,
in SCAReal64 dtime,
in SCAInt64 isunit,
in DynInt64 idata,
in DynReal64 rdata,
};
}; // sepfor
}; // Contact
}; // Uds
}; // Obj
}; // MDSolver
}; // SCA
Note: The EXT_SEPFOR user subroutines are not available with segment-to-segment contact.
Main Index
Utility Routines
C++
SCAResult Contact::usrSepfor_32(SCAReal64& fnorm, SCAReal64& ftang, const SCAInt32 ibody, const SCAInt32 nnode,
const SCAInt32 inc, const SCAReal64 time, const SCAReal64 dtime, const SCAInt32 isunit,
const sepfor::DynInt32& idata, const sepfor::DynReal64& rdata, const sepfor::DynInt32&
cidata)
{
return SCASuccess;
}
SCAResult Contact::usrSepfor_64(SCAReal64& fnorm, SCAReal64& ftang, const SCAInt64 ibody, const SCAInt64 nnode,
const sepfor::DynInt64& idata, const sepfor::DynReal64& rdata, const sepfor::DynInt64&
cidata)
{
return SCASuccess;
}
FORTRAN
subroutine ext_sepfor(fnorm, ftang, ibody, nnode, inc, time,
& dtime, isunit, idata, rdata, cdata, len_idata,
implicit none
integer, intent(in) :: ibody, inc, nnode, isunit
real(8), intent(out) :: fnorm, ftang
! call sepfor(fnorm, ftang, ibody, nnode, inc)
end subroutine ext_sepfor
Example
If the user does not want any separation of nodes from surface 3, but wants to leave the default separation
force unchanged for all other contact bodies, the BCONUDS input can be written as
Required Input:
IBODY is the current body number the node touched.
NNODE is the current touched external node number.
INC is the current increment number.
Required Output:
FNORM is the normal separation force to be supplied by the user.
FTANG is the tangential separation force to be supplied by the user.
Main Index
Utility Routines
66
BCONUDS,3,BCBODY,sname,SEPFOR
,REAL,1.e20,
where sname is the service name for this user subroutine; and the user code is written as
FNORM=radta(1)
EXT_SEPSTR
Definition of Separation Stress
Description
This user subroutine allows the definition of the separation stress in contact analysis. The separation
stresses, SNORM and STANG, are either calculated by the program or entered through the BCTABLE or
BCPARA option, and then passed into this user subroutine. The user decides whether these values at the
current increment are appropriate to determine whether separation occurs.
SNORM is the normal stress above which a node in contact separates from a surface. Any compressive or
negative value indicates real contact while a positive reaction force indicates a tendency to separate. The
default is taken as the maximum value of the residual force in the structure for the current increment
divided by an effective area. This value can be reset by the user through the input format. Defining a too
small value can result in an increased number of iterations. Defining a very large value eliminates the
possibility of separation. STANG is the tangential stress used to determine whether a nodal point
positioned at a convex corner of surface should be sliding from patch to patch or remaining on its current
patch. The default value is half of SNORM. These two default values vary from increment to increment.
BCONUDS activates the call to contact related user subroutines such as EXT_SEPSTR, and defines the
EXT_SEPSTR application:
BCONUDS,bid,BCBODY,sname,SEPSTR,
,INT,
,REAL,
,CHAR,
EXT_SEPSTR with the key word INT (REAL, CHAR).
Note: The EXT_SEPSTR user subroutines are not available with segment-to-segment contact.
Main Index
Utility Routines
Format
IDL
module SCA {
module MDSolver {
module Obj {
module Uds {
module Contact {
module sepstr {
interface SCAIMDSolverSepstr : SCAIService
{
SCAResult usrSepstr_32( out SCAReal64 snorm,
out SCAReal64 stang,
in SCAInt32 ibody,
in SCAInt32 nnode,
in SCAInt32 inc,
in SCAReal64 time,
in SCAReal64 dtime,
in SCAInt32 isunit,
in DynInt32 idata,
in DynReal64 rdata,
SCAResult usrSepstr_64( out SCAReal64 snorm,
out SCAReal64 stang,
in SCAInt64 ibody,
in SCAInt64 nnode,
in SCAInt64 inc,
in SCAReal64 time,
in SCAReal64 dtime,
in SCAInt64 isunit,
in DynInt64 idata,
in DynReal64 rdata,
};
}; // sepstr
}; // Contact
}; // Uds
}; // Obj
}; // MDSolver
}; // SCA
C++
SCAResult Contact::usrSepstr_32(SCAReal64& snorm, SCAReal64& stang, const SCAInt32 ibody, const SCAInt32 nnode,
const sepstr::DynInt32& idata, const sepstr::DynReal64& rdata, const sepstr::DynInt32&
cidata)
{
return SCASuccess;
Main Index
Utility Routines
68
}

SCAResult Contact::usrSepstr_64(SCAReal64& snorm, SCAReal64& stang, const SCAInt64 ibody, const SCAInt64 nnode,
const sepstr::DynInt64& idata, const sepstr::DynReal64& rdata, const sepstr::DynInt64&
cidata)
{
return SCASuccess;
}
FORTRAN
subroutine ext_sepstr(snorm, stang, ibody, nnode, inc, time,
& dtime, isunit, idata, rdata, cdata, len_idata,
implicit none
integer, intent(in) :: ibody, inc, nnode, isunit
real(8), intent(out) :: snorm, stang
! call sepstr(snorm, stang, ibody, nnode, inc)
end subroutine ext_sepstr
EXT_UBSQUEAL
Define Parameters used in Brake Squeal Analysis
Description
User subroutine EXT_UBSQUEAL is used to define the friction coefficient and the effective stiffness in
the brake squeal analysis in MSC Nastran. This routine is called for those nodes that are in contact with
Required Input:
IBODY is the current body number the node touched.
NNODE is the current touched external node number.
INC is the current increment number.
Required Output:
SNORM is the normal separation stress to be supplied by the user.
STANG is no longer used - dummy variable.
Main Index
Utility Routines
rotor. The parameters used for brake squeal analysis are defined in bulk data option BSQUEAL. Among
these parameters, the friction coefficient and the effective stiffness can be re-set during the process of
analysis by means of user subroutine EXT_UBSQUEAL.
BCONUDS activates the call to contact related user subroutines such as EXT_UBSQUEAL, and defines
the data (integer, real and characters) required in the user subroutine. It should look like the following for
EXT_UBSQUEAL application:
BCONUDS,bid,BCBODY,sname,UBSQUEAL,
,INT,
,REAL,
,CHAR,
EXT_UBSQUEAL with the key word INT (REAL, CHAR).
Format
IDL
module SCA {
module MDSolver {
module Obj {
module Uds {
module Contact {
module ubsqueal {
interface SCAIMDSolverUbsqueal : SCAIService
{
SCAResult usrUbsqueal_32( in DynInt32 ibodies,
in SCAInt32 nnode,
in DynInt32 nodes,
in DynReal64_2 coords,
in DynReal64 center,
in DynReal64 vector,
in SCAReal64 area,
in SCAInt32 i2or3,
in SCAReal64 temp,
in SCAReal64 press,
in DynReal64 xnorm,
Main Index
Utility Routines
70
in SCAInt32 inc,
out SCAReal64 stiff,
out SCAReal64 fric,
in SCAInt32 isunit,
in DynInt32 idata,
in DynReal64 rdata,
SCAResult usrUbsqueal_64( in DynInt64 ibodies,
in SCAInt64 nnode,
in DynInt64 nodes,
in DynReal64_2 coords,
in DynReal64 center,
in DynReal64 vector,
in SCAReal64 area,
in SCAInt64 i2or3,
in SCAReal64 temp,
in SCAReal64 press,
in DynReal64 xnorm,
in SCAInt64 inc,
out SCAReal64 stiff,
out SCAReal64 fric,
in SCAInt64 isunit,
in DynInt64 idata,
in DynReal64 rdata,
};
}; // ubsqueal
}; // Contact
}; // Uds
}; // Obj
}; // MDSolver
}; // SCA
C++
SCAResult Contact::usrUbsqueal_32(const ubsqueal::DynInt32& ibodies, const SCAInt32 nnode, const
ubsqueal::DynInt32& nodes,
const ubsqueal::DynReal64_2& coords, const ubsqueal::DynReal64& center,
const ubsqueal::DynReal64& vector, const SCAReal64 area, const SCAInt32 i2or3,
const SCAReal64 temp, const SCAReal64 press, const ubsqueal::DynReal64& xnorm,
const SCAInt32 inc, SCAReal64& stiff, SCAReal64& fric, const SCAInt32 isunit,
const ubsqueal::DynInt32& idata, const ubsqueal::DynReal64& rdata,
const ubsqueal::DynInt32& cidata)
{
return SCASuccess;
}
SCAResult Contact::usrUbsqueal_64(const ubsqueal::DynInt64& ibodies, const SCAInt64 nnode, const
ubsqueal::DynInt64& nodes,
const ubsqueal::DynReal64_2& coords, const ubsqueal::DynReal64& center,
const ubsqueal::DynReal64& vector, const SCAReal64 area, const SCAInt64 i2or3,
const SCAReal64 temp, const SCAReal64 press, const ubsqueal::DynReal64& xnorm,
const SCAInt64 inc, SCAReal64& stiff, SCAReal64& fric, const SCAInt64 isunit,
const ubsqueal::DynInt64& idata, const ubsqueal::DynReal64& rdata,
const ubsqueal::DynInt64& cidata)
{
return SCASuccess;
}
FORTRAN
subroutine ext_ubsqueal(ibodies, nnode, nodes, coords, center,
& vector, area, i2or3, temp, press, xnorm, inc, stiff,
& fric, isunit, idata, rdata, cdata, len_idata,
Main Index
Utility Routines
implicit none
integer, intent(in) :: nnode, i2or3, inc, isunit
real(8), intent(in) :: area, temp, press
real(8), intent(out) :: stiff, fric
integer, intent(in), dimension(2) :: ibodies
integer, intent(in), dimension(nnode) :: nodes
real(8), intent(in), dimension(i2or3, nnode) :: coords
real(8), intent(in), dimension(i2or3) :: center
real(8), intent(in), dimension(i2or3) :: vector
real(8), intent(in), dimension(i2or3) :: xnorm
end subroutine ext_ubsqueal
Required Input
IBODIES ibodies(1) is the touching body ID
ibodies(2) is the touched body ID
NNODE is the number of nodes
NODES nodes(1) is the touching node ID (user defined)
nodes(2:nnode) are the node IDs of touched face (user defined)
COORDS coord(i2or3,1:1) are the coordinate of touching node
coord(1:i2or3,2:nnode) are the coordinate of nodes of
touched face (L)
CENTER is the position of center of rotation axis (L)
VECTOR is the vector of rotation axis (L)
AREA is the effective area at node(1) (L2)
I2OR3 is two in a 2-D mode
is three in a 3-D model
TEMP is the temperature at the contacting node
PRESS is the contact pressure at the contacting node (F/L2)
XNORM is the normal to touched face
INC is the increment number
Main Index
Utility Routines
72
Required Output
STIFF is the average normal stiffness at the touched node (F/L3)
FRIC is the friction coefficient at the touched node
Main Index
Chapter 2: User Defined Module Service UDMSRV
2
User Defined Module Service
UDMSRV
User Defined Module Service UDMSRV 2
Utility services 4
Memory management interface 5
Database access: 6
Main Index
User Defined Module Service UDMSRV
2
Introduction
A new module called UDMSRV has been added to the set of DMAP modules accessible from the
standard user interface (input file). By default, the new module is simply a place holder for potential user
developed DMAP module functionality. There is a predefined list of input and output datablocks, but
these may be matrix or table datablocks defined in any order, according to the user's requirements, up to
a maximum of 25 inputs and 25 outputs; any or all inputs and outputs may be purged. As with any other
DMAP module, the parameter list has predefined data types; the first parameters is reserved to define the
service name of the user defined module. The UDMSRV module may also read and write to one or more
scratch datablocks, again as required according to the functionality of the module. The UDMSRV
module is callable as any other DMAP module and may be used as such in DMAP sequences and alters.
UDMSRV module provides a mechanism for Nastran users to develop their own user defined modules
and integrate them into Nastran's solution sequence through DMAP solution sequences. The module
services are callable from DMAP programming language.
To activate user defined services (UDMSRV) you will need to follow these steps:
1. Add a CONNECT entry to FMS section, e.g: CONNECT SERVICE statement
2. Add an alter to insert UDMSRV model in the DMAP solution sequence
3. Implement the user defined module service in C++ for each of the Service Module referenced in
the DMAP UDMSRV
Since the UDMSRV is a DMAP module, DMAP code rules such as Last Time Use, Output Twice, will
be applied to the datablocks referenced in the UDMSRV module. The database clean up will be made
after UDMSRV completed execution as in a regular Nastran Module.
The DMAP signature for UDMSRV models is as follows:
25 input datablocks
25 output datablocks
25 scratch datablocks
- 1 string parameter (8 character long); this is alias name of the service defined in CONNECT
SERVICE statement
10 integer parameters, default value is 0
10 real double parameters default value is 0.d0
10 string parameters, non default value
Example format and syntax of the UDMSRV DMAP statement:
UDMSRV input1,..,input25/
output1,...,outout25/
mysrv1,
Main Index
3 Chapter 2: User Defined Module Service UDMSRV
Iparm1,,,Iparam10,
RDparam1,...RDparam10,
Cparam1,...Cparam10 $
Example for the job data input to run UDMSRV:
$ Prepare the connection for 2 User Define Modules, mysrv1 and mysrv2
$
CONNECT SERVICE mysrv1 'Test.MySrv1'
CONNECT SERVICE mysrv2 'Test.MySrv2'
$
SOL MYDMAP
COMPILE MYDMAP list
SUBDMAP MYDMAP $
TYPE DB,ZUZR11 $
$
TYPE PARM,NDDL,I,N,ZUZR1
ZUZR1=100 $
$
$ Call mysrv1 to pack a matrix ZUZR1
$ Note that ZUZR11 is the first output datablock on the DMAP
$
UDMSRV ,/ ZUZR11 / 'mysrv1'/s,N,zuzr1 $
$
$ Call mysrv2 to unpack a matrix ZUZR1
$ Note that ZUZR11 is the first input datablock on the DMAP
$
UDMSRV ZUZR11 / / 'mysrv2' $
$
end $
diag 8
cend
begin bulk
end data
Main Index
Utility services
4
Utility services
A set of utility interfaces are available to provide access to Nastrans working memory area (scratch
memory) and to allow users to read and write to and from Nastran database (IO subsystem). In MD 2010
these interfaces are only directly available in C++ service implementations. This means that there are no
Fortran callable interfaces available. Fortran callable interfaces will be supported in future releases.
Main Index
5 Chapter 2: User Defined Module Service UDMSRV
Memory management interface
Memory management interface
This interface allows users to create a memory pool within the existing memory area allocated by Nastran
application. It is worth nothing that the pools are generated within the scratch memory area, which
implies that the content on memory area is purged after exiting from the module. The interface for
memory management routines are illustrated bellow:
class IMemoryManager : public IMemoryPoolFactory
{
public:
//
// allocate - allocates a block of memory
//
virtual void *allocate( SCA::SCASizeType size ) = 0;
//
// free - releases the memory back to the pool
//
virtual void free( void *ptr ) = 0;
//
// reallocate - resizes a block of memory
//
virtual void *reallocate( void* ptr,
SCA::SCASizeType size ) = 0;
//
// allocateAndInit - allocates a block of memory and initializes it to the input bit pattern
//
virtual void *allocateAndInit( SCA::SCASizeType size,
SCA::SCAUInt8 bitPattern = 0 ) = 0;
//
// clear - releases all memory allocated by the pool
//
//virtual void clear() = 0;
//
// largestAvailableBlockSize - returns the size of the largest chunk of available memory in
bytes
//
virtual SCA::SCASizeType largestAvailableBlockSize( SCA::SCABool quick = false ) = 0;
//
// tagMemoryPool - assigns an alias (a string name) to the memory pool
// returns 0 on success
// 1 if the name already exists
// 2 if the pool already has another tag
// 3 if the name is "" (blank)
//
virtual int tagMemoryPool( const SCA::SCAString& tag, SCA::MemoryPool& pool ) = 0;
//
// findMemoryPool - finds the an alias (a string name) to the memory pool
// returns 0 on success
// 1 if the name does not exist exists
//
virtual int findMemoryPool( const SCA::SCAString& tag, SCA::MemoryPool& pool ) = 0;
};
Main Index
Database access:
6
Database access:
The interface to Nastran IO subsystem is done through a service called GinoEmb. The prototype for this
service resides in SCAIGinoEmbService.h that is part of Nastran delivery. Below are the available
methods:
SCAResult setFileHandle(in SCAInt32 handle);
SCAResult getFileHandle(out SCAInt32 handle);
SCAResult open(in SCAInt32 mode, out SCAInt32 code);
SCAResult close(in SCAInt32 code);
SCAResult readTrailer(out SCAInt32Sequence trailer);
SCAResult writeTrailer(in SCAInt32Sequence trailer);
SCAResult read(in SCAString schema, out SCAAnySequence blob, out
SCABool endOfRecord, out SCABool endOfFile);
SCAResult write(in SCAAnySequence blob, in SCAInt32 eorCode);
SCAResult skipRecord(in SCAInt32 numberOfRecords);
SCAResult useMachinePrecision(in SCABool flag);
SCAResult useNastStringSize(in SCABool flag);
SCAResult dbcreate( in SCAString cstr, out SCAInt32 handle, out
SCAInt32 stat);
SCAResult getName( out SCAString fname);
SCAResult locate( in IDType recordID, out SCAInt32Sequence flag );
The schema for read a write operation is a sequence of type code that matches the content of the data
sequence that is to be read/written to the database file. Currently Nastran database supports the following
type codes:
TCID_Int32: // 32 bit integer
TCID_Int64: // 64 bit integer
TCID_Real32: // 32 bit real
TCID_Real64: // 64 bit real
TCID_String: // string
TCID_Bool: // Boolean
Code examples:
Please refer to examples that are supplied under <MSC_VERD>/nast/services directory.
Main Index
Chapter 3: OpenFSI
3
OpenFSI
Introduction 8
Running an OpenFSI MSC Nastran simulation 11
Creating an OpenFSI SCA service 22
Appendix 25
References 39
Main Index
Introduction
8
Introduction
The OpenFSI functionality provides a mechanism to exchange fluid structure interaction data between
the MSC Nastran
TM
solver and an external code. The nonlinear solution sequence in MSC Nastran
(SOL400) reads nodal force vectors from the external code, and sends back nodal displacement and
velocity vectors. Data communication is done using the OpenFSI interface on nodes that belong to so-
called wetted surfaces, which are the surfaces where the fluid is in contact with the solid structures. This
data transfer is done once or several times per time step in a transient simulation. The surface elements
and corresponding nodes that belong to wetted surfaces are defined in the Nastran input deck [1.], and
are sent to the external code in the initialization stage, before the transient loop. At the conclusion of the
transient loop, a message indicating that the simulation is set to terminate is sent to the external code. An
overview of the simulation scenario is shown in Figure 3-1.
Figure 3-1 Basic flow chart of an OpenFSI simulation.
Wetted surfaces for Nastran and the external CFD code may use dissimilar mesh discretizations, see
Figure 3-2, in which case the data must be mapped by the external code since MSC Nastran only
communicates the data on the wetted nodes corresponding to the wetted surfaces defined in the Nastran
input deck.
Main Index
9 Chapter 3: OpenFSI
Introduction
Figure 3-2 Example of CFD and MSC Nastran wetted surface meshes.
A schematics of the data flow using the OpenFSI interface is shown in Figure 3-3. The OpenFSI interface
is implemented using a Simulation Component Architecture (SCA) [2., 3., 4.], which allows for
communication from MSC Nastran to a different process, possibly running on a different computer.
Figure 3-3 Schematics of OpenFSI interface. Nastran reads force vectors from the external
(CFD) code, and sends displacement and velocity (not shown) vectors back.
Main Index
Introduction
10
To run an OpenFSI simulation the following software components are required:
MSC Nastran 2012 (or later).
An OpenFSI SCA component.
External code with OpenFSI interface implementation.
OpenFSI SCA components can be of two types:
1. Prebuilt components used with certain commercial CFD solvers.
2. User defined SCA components built with the OpenFSI software development kit (SDK).
This document will explain how to run an OpenFSI simulation using an existing OpenFSI SCA
component, and how to build a user defined OpenFSI SCA component.
Main Index
Running an OpenFSI MSC Nastran simulation
OpenFSI input deck
To define an OpenFSI simulations, there are essentially two fundamental entities that must be added to
the Nastran input deck: (i) the OpenFSI SCA service component, which is a single entry in the file
management section, and (ii) the wetted surface data where the loads are applied, which consist of one
entry in the case control section, and several entries in the bulk data section. The constituents related to
the definition of an OpenFSI input deck are given in Table 3-1.
Table 3-1 Nastran input file entries related to OpenFSI simulations.
As indicated above, for a user to run a simulation using the OpenFSI interface, a SCA service must be
defined in the file management section in the Nastran input file. The SCA service is associated with one
ore more wetted surfaces defined in the bulk data section in the input file. The connection between the
SCA service and a wetted surface is done by defining a load on the wetted surface, which is tagged with
the SCA service name. The load on the wetted surface is specified as a dynamic load in the case control
section in the Nastran file, but it must be done using a TLOAD1 bulk data entry. To this end, the DLOAD
entry in the case control section references a TLOAD1 entry in the bulk data section, which in turn
references the load on the wetted surface, defined by the new WETLOAD entry. The structure of a Nastran
input deck for a single wetted surface and load is shown in Table 3-2, and for multiple wetted surfaces
and loads in Table 3-3.
Main Index
12
Table 3-2 Nastran input file structure for single wetted load WL1, and a single wetted
surface WS1. Note that the service name (here SCAFSI) is converted to all
upper case characters if lower case characters are used, and that the external
service ExternalCodeVendor.OpenFSImust be given with (right) single quotes,
and only one space character may be used as separator between the key words
in the file management section.
The dependency between the entries used for OpenFSI using a single load (with input file structure as
Table 3-2) is illustrated in the diagram below:
Main Index
Note: Unless indicated differently, the entries are defined in the bulk data section in the Nastran
input file.
Main Index
14
Table 3-3 Nastran input file structure for multiple wetted loads WL1, WL2,... and multiple
wetted surfaces WS1, WS2, .... For OpenFSI, the DLOAD scale factors should
be unity, S=S1=S2= ... =1:0.
If a linear combination of TLOAD1 entries are specified in the DLOAD bulk data entry (as in Table 3-3),
we have the dependency between the entries used for OpenFSI as follows:
Main Index
The definitions of the OpenFSI bulk data entries are given in Table 3-4,Table 3-5, Table 3-6, Table 3-7,
Table 3-8. The FSICTRL and WETLOAD entries reference SERV ID, an OpenFSI SCA service. If more
than one FSICTRL and WETLOAD entries are used, they may reference different OpenFSI SCA services,
which is useful if different external codes are used for different sets of wetted surfaces. Two different
approaches may be used to define the wetted surface elements: (i) Using the WETELMG entry, the grid
points making up a wetted element are specified explicitly; or (ii) using the WETELME entry, a wetted
element is defined by referencing a face (or a side) of a parent structural element.
Format: FSICTRL
Examples:
Table 3-4 Definition of a FSICTRL entry.
1 2 3 4 5 6 7 8 9 10
FSICTRL SERV_ID TYPE FREQ
FSICTRL SCAFSI
EXPLICIT
1
Field Contents Type Default
SERV_ID OpenFSI SCA service name associated with the wetted
surface loads. The OpenFSI SCA service is defined using
the CONNECT SERVICE File Management Section
statement
Character None
TYPE Type of solution strategy coupling between the external
code and MSC Nastran. TYPE can be either EXPLICIT
or IMPLICIT.
Character EXPLICIT
FREQ External force and displacement update frequency per
time step, for the exchange with the external code using
the IMPLICIT solution strategy TYPE.
Integer > 0 1
DLOAD
WETSURF
WETELME WETELMG
Case Control File Management
OpenFSI
SCA service
TLOAD1 WETLOAD FSICTRL DLOAD
Main Index
16
Format: WETLOAD
Example:
Table 3-5 Definition of a WETLOAD entry.
1 2 3 4 5 6 7 8 9 10
WETLOAD
WLID WSID SERV_ID
WETLOAD
1 1001 SCAFSI
WLID Load set ID, referenced by the EXCITEID field in the
TLOAD1 entry.
INTEGER > 0 None
WSID Wetted surface identification number. The wetted surface
must be defined in the WETSURF Bulk Data entry.
INTEGER > 0 None
SERV_ID OpenFSI SCA service name associated with the wetted
surface loads. The OpenFSI SCA service is defined using the
CONNECT SERVICE file management section entry..
CHARACTER None
Main Index
Format: WETSURF
Alternate Format:
Example:
Table 3-6 Definition of a WETSURF entry.
1 2 3 4 5 6 7 8 9 10
WETSURF
WSID WTAG
WEID1 WEID2 WEID3 WEID4 WEID5 WEID6 WEID7 WEID8
WEID9 WEID10 -etc.-
WETSURF
WSID WTAG
WEID1 THRU WEID2 BY INC
WETSURF
10001 wall1
5 THRU 21 BY 4
27 30 33
35 THRU 44
67 68 70 72 77 82 86 79
89 THRU 110 BY 3
WSID Wetted surface identification number. INTEGER > 0 None
WTAG Wetted surface tag name exported to an external code
using the OpenFSI SCA interface.
CHARACTER None
WEID1,
WEID2, ...
Wetted element identification numbers defined using the
WETELMG or WETELME Bulk Data entries.
INTEGER > 0 None
THRU, BY Keywords to specify a range of wetted elements. CHARACTER None
INC Increment to use with the THRU and BY keywords. INTEGER > 0 1
Main Index
18
Format: WETELMG
Example:
Table 3-7 Definition of a WETELMG entry.
Format: WETELME
Example:
Table 3-8 Definition of a WETELME entry.
1 2 3 4 5 6 7 8 9 10
WETELMG
WEID TYPE
G1 G2 G3 G4 G5 G6 G7 G8
WETELMG
10001 QUAD4
23 35 124 28
WEID Wetted element identification number. INTERGER > 0 None
TYPE Wetted element type, which can be any of TRIA3,
TRAI6, QUAD4, QUAD8, LINE2 or LINE3.
CHARACTER None
G1, ..., G8 Grid point identification numbers for the wetted surface
element WEID.
INTERGER > 0 None
1 2 3 4 5 6 7 8 9 10
WETELME
WEID EID SIDE
WETELME
10001 34 3
WEID Wetted element identification number. INTERGER > 0 None
EID Structural element identification number, which
corresponds to a surface element CQUAD4, CQUAD8,
CQUADR, CQUAD, CTRIA3, CTRIA6, CTRIAR; or
a solid element CTETRA, CPENTA, or CHEXA.
INTERGER > 0 None
SIDE Side identification number of element EID. 1 s INTEGER s 6 None
Main Index
Running MSC Nastran
To run an OpenFSI MSC Nastran simulation, a SCA service catalog, which contains references to
available SCA services components, and an associated library path, pointing to the interface functions
library, must be specified. A resource directory may also be specified. This is done by setting
environment variables as follows:
setenv SCA SERVICE CATALOG $SCAPATH/Apps/res/SCAServiceCatalog.xml
setenv SCA LIBRARY PATH $SCAPATH/Apps/LX8664/lib/
setenv SCA RESOURCE DIR $SCAPATH/Apps/res/
if a csh shell is used. Here $SCAPATH refers to the path where the SCA service components are installed
on the system. For a Bourne shell, like sh or bash, the environment variables are defined as:
export SCA SERVICE CATALOG=$SCAPATH/Apps/res/SCAServiceCatalog.xml
export SCA LIBRARY PATH=$SCAPATH/Apps/LX8664/lib/
export SCA RESOURCE DIR=$SCAPATH/Apps/res/
To execute Nastran with the input deck model.dat simply enter the following line:
nastran model.dat
(See section Run time errors and debugging for possible run time errors, if there is a problem.)
A simple example model
Table 3-9 shows a trivial example with three elements, where the two triangular elements CTRIA3
belong to a wetted surface srf1, and the single quadrilateral element CQUAD4 belongs to a different
wetted surface srf2. The format of this input deck can easily be extended to a larger mesh by defining
multiple GRID, CTRIA3 or CQUAD4 entries and the corresponding WETELMG, WETSURF and
WETLOAD entries. To run this model, the service myService.OpenFSI must be available as a SCA
component, with the corresponding SCAServiceCatalog.xml file and library, e.g.
libmyService.so.
To run the example input deck example.dat (defined in Table 3-9) in a csh shell, the following procedure
is used:
setenv SCA SERVICE CATALOG $SCAPATH/Apps/res/SCAServiceCatalog.xml
setenv SCA LIBRARY PATH $SCAPATH/Apps/LX8664/lib/
setenv SCA RESOURCE DIR $SCAPATH/Apps/res/
where $SCAPATH is replaced by the path to the SCA service installation on the local machine where
MSC Nastran is to be executed. MSC Nastran can now be executed:
Note: For Windows NT/XP, the library paths are:
setenv SCA SERVICE CATALOG $SCAPATHnAppsnresnSCAServiceCatalog.xml
setenv SCA LIBRARY PATH $SCAPATHnAppsnWINNTnbin
setenv SCA RESOURCE DIR $SCAPATHnAppsnres
For the R4 DEV beta version enter: nastran sys444=1 delete=IFPDAT
model.dat
Main Index
20
nastran example.dat
Note that this procedure will execute MSC Nastran which will make function calls to the OpenFSI SCA
service during execution. If the specified OpenFSI SCA implementation depends on an additional
process that the OpenFSI SCA module relies on, as in the case of some CFD solver implementations, that
process must be launched separately. Follow the instructions for the particular CFD solver in question on
how to launch that process.
Note: For the R4 DEV beta version enter: nastran sys444=1 delete=IFPDAT
example.dat
Main Index
Table 3-9 Nastran example input deck: example.dat.
Main Index
Creating an OpenFSI SCA service
22
Build tools and source files
To create a user defined OpenFSI SCA service, the SDK provided with the MSC Nastran distribution is
used. In addition, a C/C++ compiler is needed to compile the source code. The SCA services are built
using the scons tools included in the distribution. First set the following enviroment variables to point to
the install directory, e.g:
setenv SCONS TOOLS $SDKPATH/solver sdk/Tools
setenv APPS SYSTEM $SDKPATH/solver sdk/SCAKernel
where $SDKPATH is replaced by the path to the SDK installation.
The environment variables C and CXX specifies the C and C++ compiler paths, and the environment
variable CCOMPILER specifies the vendor, which can be intel or gcc. See [2.] for more details.
To build a user defined OpenFSI service called myOpenFSI the following files are needed in the source
directory:
myOpenFSI.cdl
myOpenFSI.cpp
myOpenFSI.h
myOpenFSI.sdl
OpenFSI.idl
SConscript
All these files are already created as a simple OpenFSI example located in $SDKPATH/solver
sdk/examples/Implementations/OpenFSI.
The procedure to build the SCA components in the SDK is the following:
1. Change directory to the source code root directory: $SDKPATH/examples
2. Build the SCA component from the source code root directory by simply entering scons.
The OpenFSI.idl and SConscript files that are provided with the SDK, are normally used to make
all OpenFSI services, so that only the files with root name myOpenFSI need to be recreated (or use a
different name) if a new services is created from scratch. To make a new OpenFSI component from
scratch, use the following procedure:
1. Create a new myOpenFSI.sdl file. A different name can be used if desired (but the extension
should be .sdl).
Note: To compile and create the necessary files included in a SCA component, including the
dynamic library with the OpenFSI functions.
Main Index
2. Use the executable genskeleton to create skeletons for myOpenFSI.cpp and
myOpenFSI.h, i.e. files that contain all method (function) signatures defining the OpenFSI
interface, but no source code.
3. Implement the source code in the myOpenFSI.cpp and myOpenFSI.h skeleton files.
4. Create a new myOpenFSI.cdl file
5. Build the SCA component from the source code root directory using scons.
Alternatively, its possible to only build the OpenFSI SCA component as follows:
1. Locate the OpenFSI.idl file and copy to the source directory.
2. Create a new myOpenFSI.sdl file.
3. Use the executable genskeleton to create skeletons for myOpenFSI.cpp and myOpenFSI.h,
i.e. files that contain all method (function) signatures defining the OpenFSI interface, but no
source code.
4. Implement the source code in the myOpenFSI.cpp and myOpenFSI.h skeleton files.
5. Create a new myOpenFSI.cdl file.
6. Build the SCA component from the OpenFSI source code directory by entering scons --qb4.
To include a static library add the following line to the SConscript file:
env.AddLinkLibrary("$LIBPATH/lib/libMyLib.a")
where $LIBPATH is the path to the install location of the library.
To include a dynamic library add the following line to the SConscript file:
env.AddLinkSharedLibrary("$LIBPATH/lib/libMyLib.so")
The document [3.] provides a tutorial on how an interface definition file (an .idl file) is created from
scratch, along with the creation of the service definition (.sdl) and component definition (.cdl) files.
Here, the interface definition file is already provided (see Interface Definition Language file), and the
service and component definition files provide the interface for only one component, so the content in
those files is straightforward (see Service Definition Language file and Component Definition Language
file). An overview of the interface definition and implementation of the OpenFSI methods is given in the
next section.
OpenFSI interface and implementation
As mentioned above, the interface for the OpenFSI SCA component is defined in the OpenFSI.idl
file, see Section Interface Definition Language file, which provides the Application Programming
Interface (API) for implementing the external code connecting to the MSC Nastran solver.
The interface has the following basic structure for the solution data transfer:
Initialization stage:
initialize( wettedSurfaceMesh, initialCondition)
Main Index
24
Solver stage:
initializeTimeStep( time, deltaTime)
: getWettedNodeForces( wettedNodeForces )
putWettedNodeDisplacementsAndVelocities(
wettedNodeDisplacement , wettedNodeVelocities)
finalizeTimeStep(time)
Finalize stage:
terminate(message)
where indicates that discretization or solution data is sent from MSC Nastran to the service; :
indicates
that force data is sent from the service and received by MSC Nastran; and indicates that time and time
step data is sent from MSC Nastran to the service and (possibly different) time step received by MSC
Nastran. See also section OpenFSI data flow.
To generate the skeleton code where the service methods are implemented, enter:
genskeleton myOpenFSI.sdl
This command will create the skeleton code files myOpenFSI.cpp and myOpenFSI.h, based on the
OpenFSI.idl file within the name space provided in myOpenFSI.sdl. The header file
myOpenFSI.h contains the declarations for the OpenFSI service myOpenFSI. The service
implementation file myOpenFSI.cpp contains a constructor and a destructor for the service object,
along with prototypes for the OpenFSI service methods that need to be populated with source code.
Once the source code has implemented, and the component definition file myOpenFSI.cdl has been
created, the service component is built using scons from the source code root directory. Just enter:
scons
from the directory where the SConstruct file is located. This command should create the OpenFSI
SCA component files, including the service catalog file SCAServiceCatalog.xml in the Apps/res
directory and e.g. the library libmyService.so in the Apps/LX8664/lib for a Linux x86 64
system. The library name and directory name will depend on the platform where the SCA component is
built. The location must be consistent with the path defined by the environment variables SCA SERVICE
CATALOG, SCA LIBRARY PATH and SCA RESOURCE DIR when executing MSC Nastran.
See section Run time errors and debugging for possible run time errors and debugging options.
Note: Excluding the simulation control flags redoTimeStep and endSimulation, which data
transfer is bidirectional. The exact definition of the interface is given in Section Interface
Definition Language file.
Main Index
Appendix
Appendix
Interface Definition Language file
The IDL file used to build a SCA service connecting to the OpenFSI interface has the following form:
#ifndef SCA MDSOLVER UTIL OPENFSI OPENFSI IDL INCLUDED
#define SCA MDSOLVER UTIL OPENFSI OPENFSI IDL INCLUDED
#include "SCA/Service.idl"
module SCA f module MDSolver f module Util f module OpenFSI f
///
/// The following Type is used to define the "wetted element".
///
enum wettedElementType
{
TRIA,
QUAD,
LINE
}
/// WETTED NODE:
///
/// The "wettedNode struct" consists of a grid point ID and a triplet
of 64 bit real numbers.
///
/// The grid point ID is a unique integer identifier for the wetted
grid point.
///
/// The triplet is used to define any of the following:
/// (X,Y,Z) coordinates of the wetted grid point in the underformed
(stress-free) configuration of the structure.
/// (Ux,Uy,Uz) components of its TOTAL displacements.
/// (Vx,Vy,Vz) components of its velocity.
/// (Fx,Fy,Fz) components of the fluid force acting on it.
/// ALL the previous, measured in an orthogonal Cartesian coordinate
system which is referred to as the "BASIC" coordinates system.
///
/// Remark 1:
/// Let (X,Y,Z) be the UNDEFORMED (STRESS-FREE) coordinates of a given
wetted grid point.
/// Let (X0,Y0,Z0) be the coordinates of the same wetted grid point at
the initial time t=0.
/// Let (Xt,Yt,Zt) be the coordinates of the same wetted grid point at
the current time t.
/// By TOTAL displacements (at time t) we mean (Uxt,Uyt,Uzt) =
(Xt,Yt,Zt) - (X,Y,Z)
/// By TOTAL displacement at initial time t=0 (or INITIAL TOTAL
displacements) we mean (Ux0,Uy0,Uz0) = (X0,Y0,Z0) - (X,Y,Z)
/// Remark 2:
Main Index
Appendix
26
/// Notice that the undeformed configuration (or coordinates) of the
structure might be different from its INITIAL configuration.
/// In other words, at the initial time t=0, the structure might be
"displaced" from its Undeformed or stress-free configuration.
/// i.e, (X,Y,Z) might be different from (X0,Y0,Z0) and therefore
(Ux0,Uy0,Uz0) might be different from (0,0,0).
/// However, this INITIAL TOTAL displacement IS NOT CAUSED by fluid
forces but by other factors totally independent from the fluid.
/// Remark 3:
/// The TOTAL displacements shouldnt be confused with the so called
INCREMENTAL displacements which
/// measure the displacement of a grid point between time "t" and the
next time step "t+dt".
/// The structure code is concerned with the TOTAL displacements but
NOT the incremental displacements.
/// Remark 4:
/// By undeformed (or stress-free) configuration we mean the position
of the structure when all forces are zero (either fluid or non-fluid
related).
/// and all (Dirichlet) boundary conditions and initial conditions
are zero.
///
struct wettedNode
{
SCAInt64 id;
SCAReal64 x;
SCAReal64 y;
SCAReal64 z;
};
/// WETTED ELEMENT:
///
/// A wetted element is either a line (with 2 or 3 nodes),
quadrilateral (with 4 or 8 nodes) or a triangle (with 3 or 6 nodes).
/// A wetted element is defined by specifying its type, and its
connectivity table.
/// Grid points are listed in the following order:
/// G3
/// G1 o---o---o G2
///
///
///
/// G3 G4 G7 G3
/// o o-------o------o
Main Index
Appendix
/// / \ | |
/// G6 o o G5 G8 o o G6
/// / \ | |
/// o------o------o o-------o-------o
/// G1 G4 G2 G1 G5 G2
///
/// The type (type) can be either LINE, TRIA or QUAD
/// The number of Nodes (numberOfNodes) can be either 2,3 for LINE, or 3,6 for
TRIA or 4,8 for QUAD.
///
/// Notice that for quadratic triangles (TRIA-6) or quadratic quadrilaterals
(QUAD-8), the
/// corner grid points are mandatory (nonzero grid ids), however the mid-edge
grid points might be zero.
///
/// In other words, we are allowing the possibility of "incomplete quadratic"
or "partially quadratic" elements
/// where some of the edges are parabolas (defined with a non-zero mid-edge
grid point) and some of the edges
/// are straight lines (defined with a zero mid-edge grid point).
///
/// For example, consider the following "incomplete quadratic" quadrilateral
with two parabolic edges and two
/// straight edges
/// G4 G7 G3
/// o-------o------o
/// | |
/// G8 o |
/// | |
/// o--------------o
/// G1 G2
///
Main Index
Appendix
28
/// In this case the TYPE is QUAD, NumberOfNodes is 8 (not 6) and the
connectivity table is the
sequence fG1,G3,G3,G4,0,0,G7,G8g
///
struct wettedElement
{
SCAInt64 id; ///id of this
wetted element
wettedElementType type; ///type of this wetted element.
either LINE, TRIA or QUAD
SCAUInt32 numberOfNodes; ///Number of nodes. 2 or 3 for LINE,
3 or 6 for TRIA; 4 or
8 for QUAD
SCAInt64Sequence connectivity; ///sequence of wetted node IDs.
};
///
/// WETTED SURFACE:
///
/// A wetted surface is a sequence or collection of wetted elements.
/// For each wetted surface, we define also an integer identification
number and a character label.
///
typedef sequence<wettedElement> wettedElementSeq;
struct wettedSurface
{
SCAInt64 wettedSurfaceId; ///Integer ID
of this wetted surface
SCAString wettedSurfaceTag; ///Character string
tag to identify this surface
wettedElementSeq wettedElements; ///Sequence of wetted
elements, in any order, possibly with
mixed types (TRIA and QUAD)
Main Index
Appendix
};
///
/// A wetted node sequence collects all the wetted nodes
/// This sequence will be used to get or pass any of the following
/// -Undeformed (stress-free) coordinates of wetted nodes
(wettedNodeCoordinates)
/// -Initial displacements of wetted nodes (wettedNodeDisplacements)
/// -Initial velocities of wetted nodes (wettedNodeVelocities)
/// -Current displacements of wetted nodes (wettedNodeDisplacements)
/// -Current velocities of wetted nodes (wettedNodeVelocities)
/// -Current forces on wetted nodes (wettedNodeForces)
typedef sequence<wettedNode> wettedNodeSeq;
///
/// A wetted surface sequence collects all the wetted surfaces.
///
typedef sequence<wettedSurface> wettedSurfaceSeq;
interface SCAIMDSolverOpenFSI : SCAIService
{
///
/// INITIALIZE METHOD:
///
/// The initialize method sends from the structure to the fluid the
following data:
/// 1-The UNDEFORMED or STRESS-FREE positions of "wetted" grid points.
/// 2-The initial TOTAL displacements of "wetted" grid points.
/// 2-The initial velocities of "wetted" grid points.
/// 3-The "wetted elements" with are either lines (LINE), triangles
(TRIA) or quadrilaterals (QUAD)
///

with 2,3 or 3,6 or 4,8 "wetted nodes".
Main Index
Appendix
30
////Remark 1:
/// The wetted elements are not sent as a single sequence but as a
sequence of wetted surfaces,each of which is a sequence of wetted
elements.
/// Each wetted surface is assigned and integer and character id to
help the fluid code map structural grids with fluid grids.
/// Remark 2:
/// We emphasize that the "initial" configuration (or positions) of the
structure does not necessarily coincide with the "undeformed" or
"stress-free" configuration.
/// The user of the structural code typically defines the "undeformed"
positions (X,Y,Z) and initial displacements (Ux0,Uy0,Uz0) and
velocities (Vx0,Vy0,Vz0) of
/// the structural grid points.
/// Then, the "initial positions" ( X0,Y0,Z0 ) are defined as
"undeformed position + initial displacement": ( X0,Y0,Z0 ) = (X,Y,Z) +
(Ux0,Uy0,Uz0)
/// The fluid code will get from the structural code the UNDEFORMED
positions (X,Y,Z) and initial displacements (Ux0,Uy0,Uz0)
/// (everything measured in BASIC coordinate system) but NOT the
initial positions (X0,Y0,Z0).
/// Remark 3:
/// A Wetted Surface is a collection (sequence) of "Wetted Elements"
with an integer id and a character label.
/// A "Wetted Surface Sequence" is a collection of "Wetted surfaces".
/// Remark 4:
/// Wetted surfaces can list mixed types (TRIA,QUAD) in any order.
///
SCAResult initialize( in wettedNodeSeq wettedNodeCoordinates,
///undeformed (stress-free)
coordinates of wetted nodes (X,Y,Z)
in wettedNodeSeq wettedNodeDisplacements, ///initial TOTAL
displacements of wetted nodes
(Ux0,Uy0,Uz0)
Main Index
Appendix
in wettedNodeSeq wettedNodeVelocities, ///initial TOTAL velocities
of wetted nodes (Vx0,Vy0,Vz0)
in wettedSurfaceSeq wettedSurfaces ); ///collection of wetted
surfaces (which define
the connectivity of all the elements)
///
/// Time step intitialization
///
SCAResult initializeTimeStep( in SCAReal64 time,
inout SCAReal64 deltaTime,
in SCAReal64 minimumDeltaTime,
in SCAReal64 maximumDeltaTime,
inout SCABool redoTimeStep );
///
/// Time step termination
///
SCAResult finalizeTimeStep( in SCAReal64 time,
inout SCABool endSimulation,
///
/// GET FORCES METHOD:
///
/// The getWettedNodeForces method sends the following information from
the fluid to the structure code:
/// "current" fluid forces (fx,fy,fz) acting on all wetted node "id".
/// Remark 1:
/// The forces are collected in a sequence of wettedNode struct
fid,fx,fy,fzg
/// Remark 2:
/// Forces are measured in the BASIC coordinate system.
Main Index
Appendix
32
/// Remark 3:
/// It is anticipated that the fluid mesh is different (and finer) than
the structural mesh.
/// The structural code expects forces at the structural (wetted) grid
points.
/// A "mapping" between the fluid mesh and the structural (wetted) mesh
is typically required
as part of this method.
/// The (wetted) structural mesh is provided from the structural code
to the fluid code when
the INITIALIZE method is called to facilitate this mapping if required.
///
///
SCAResult getWettedNodeForces( out wettedNodeSeq wettedNodeForces,
///
/// PUT DISPLACEMENTS AND VELOCITIES METHOD:
///
/// The putWettedNodeDisplacementsAndVelocities method sends the
following information from the structure to the fluid code:
/// "current" TOTAL displacements (Ux,Uy,Uz) of all wetted node "id".
/// "current" velocities (Vx,Vy,Vz) of all wetted node "id".
///
/// Remark 1:
/// The displacements and velocities are collected in sequences of
wettedNode struct fid,Ux,Uy,Uzg and fid,Vx,Vy,Vzg
/// Remark 2:
/// Displacements and Velocities are measured in the BASIC coordinate
system.
/// Remark 3:
/// This method concerns TOTAL displacements, i.e., displacements with
respect to the UNDEFORMED or stress-free configuration.
Main Index
Appendix
/// (as opposed to INITIAL displacements (those measured from initial
configuration) or INCREMENTAL displacements (those measured from the
previous time step).
///
SCAResult putWettedNodeDisplacementsAndVelocities( in wettedNodeSeq
wettedNodeDisplacements, ///"Current"TOTAL displacements
of wetted nodes (Ux,Uy,Uz) in wettedNodeSeq wettedNodeVelocities,
///"Current" TOTAL velocities of wetted nodes (Vx,Vy,Vz)
///
/// Termination with message
///
SCAResult terminate( in SCAString message );
};
}; }; }; };
#endif
Service Definition Language file
The OpenFSI service definition language file has the content:
#ifndef MYOPENFSI OPENFSI SDL INCLUDE
#define MYOPENFSI OPENFSI SDL INCLUDE
#include "SCA/OpenFSI.idl"
module OpenFSI {
service myOpenFSI
{
interface SCA::MDSolver::Util::OpenFSI::SCAIMDSolverOpenFSI;
};
};
#endif
Main Index
Appendix
34
Component Definition Language file
The OpenFSI component definition language file has the content:
#ifndef MYOPENFSI OPENFSI CDL INCLUDE
#define MYOPENFSI OPENFSI CDL INCLUDE
#include "myOpenFSI.sdl"
component Test.OpenFSI
{
service myOpenFSI;
};
#endif
OpenFSI data flow
The data flow for an OpenFSI MSC Nastran simulation is illustrated in Figure 3-4Figure 3-5.
Main Index
Appendix
Figure 3-4 The data flow for the MSC Nastran nonlinear solver module for an explicit
OpenFSI SCA service. This is the simplest type of service, as the nodal forces
from the external code are only read at the beginning of the time step, and the
nodal results, the displacement and velocity, are only sent at the end of the time
step. The arrows indicate the data flow besides the Boolean parameters
redoTimeStep and endSimulation.
Main Index
Appendix
36
Figure 3-5 The data flow for theMDNastran nonlinear solver module for an implicit OpenFSI
SCA service. In the implicit service, the data is communicated inside the
Newton-Raphson loop at a frequency specified by the FSICTRL entry in the
bulk data section. Note that the nodal forces are also read at the beginning of
the time step before entering the Newton-Raphson loop (not shown here), in
which case the FSI forces do not have to be read at the first iteration. The
arrows indicate the data flow besides the Boolean parameters redoTimeStep
and endSimulation.
Run time errors and debugging
Reasons for a run time failure can be:
Main Index
Appendix
Mispelled service name. If the correct service name is myOpenFSI but the service name
wrongServiceName is used in the input deck, the following error message will show in the
.f06 file:
Also note that the CONNECT SERVICE scafsi myOpenFSI statement must use a single
space as separator.
Incorrect SCA LIBRARY PATH specification gives the error message::
Note that if the library is specified to be located in a subdirectory to lib, say lib/Test, (it
will say library="Test/OpenFSI" in the SCAServiceCatalog.xml file), the
specified path should still point to lib.
Incorrect SCA SERVICE CATALOG specification gives the error message::
Note that similarity with error messages above.
Incorrect or mispelled SERV ID name in WETLOAD entry gives the error message (in the .f06)
file:
(The OpenFSI service will subsequently not be loaded.)
A WETSURF entry without a corresponding WETLOAD entry will give the error message (in the
.f06) file:
*** USER FATAL MESSAGE 7831 (SCA Service Loader)
SCA wrongServiceName service initialization failed.
SCA myOpenFSI service initialization failed.
SCA myOpenFSI service initialization failed.
Error: Missing FSICTRL
*** USER FATAL MESSAGE 13 (GPWET)
ERROR IN DMAP INSTRUCTION Incorrect number of WETSURFs
INSTRUCTION NO.WETSURFs
Main Index
Appendix
38
For the DEV R4 beta version, missing sys444=1 delete=IFPDAT options executing MSC
Nastran gives the error message::
An incorrect res/types directory gives the error (in the .log file):
(Try deleting res/types/Test/OpenFSIComp.xml.)
To include more diagnostic messages during run time, set DIAG 51 in the executive control section in
the input deck. In addition, the environment variable SCA KERNEL DEBUG can be used to debug the
SCA service, e.g:
setenv SCA KERNEL DEBUG
SvcCatalogDump=all,SvcLoad=all,SvcTableDump=all,ShrLibLoad=all.
*** SYSTEM FATAL MESSAGE 305 (IFPDRV)
IFP MODULE CANNOT OPEN GINO FILE 0
USER FATAL MESSAGE 9002 (IFPS)
Failed to initialize SCA kernel.
Error message is: SCA.SCASystemException - XML
TypeCodes: "Error 55" (ID=2000000150) ** ERROR **
SCA KERNEL INIT FAILED. STOP IN NASTMAIN
Main Index
References
References
1. MSC Nastran 2012 - Quick Reference Guide, MSC.Software Corp., 2 MacArthur Place, Santa
Ana, CA 92707, USA, (2009).
2. MSC Simulation Component Architecture IDL Language and Compiler Guide, MSC.Software
SOSP 73.XX (2005).
3. MSC Simulation Component Architecture Programming Tutorial, MSC.Software SOSP-73.XX
(2006).
4. MSC Simulation Component Architecture Build System Guide, MSC.Software SOSP-73.13
(2006).
Main Index
References
40
Main Index
Chapter 4: OpenFSI MSC Nastran & SimXpert Quick Start Tutorial
4
OpenFSI MSC Nastran &
SimXpert Quick Start Tutorial
Launch SimXpert and Import the Structural Model 42
Define the Service for the Coupled Solution 43
Define the OpenFSI LBCs (Wettted Surfaces) 44
Define a Nonlinear Simulation 46
Launch MSC Nastran OpenFSI-AcuSolve Simulation 51
Launch MSC Nastran OpenFSI-MpCCI Simulation (for Fluent &

StarCD) 52
Examine the Results Using SimXpert 53

Main Index
Launch SimXpert and Import the Structural Model
42
Launch SimXpert and Import the Structural Model
Main Index
43 Chapter 4: OpenFSI MSC Nastran & SimXpert Quick Start Tutorial
Define the Service for the Coupled Solution
Define the Service for the Coupled Solution
Note: The form above shows a generic name (myService.openFSI) for the OpenFSI Service
name. This will be translated to the Connect Service entry in the MSC Nastran input file
along with the alias Name (8 characters or less). Check for the actual service in the
SCAServiceCatalog.xml as defined by the vendor, for example, 'acuSolveService.openFSI'
Main Index
Define the OpenFSI LBCs (Wettted Surfaces)
44
Main Index
Main Index
Define a Nonlinear Simulation
46
Main Index
Main Index
48
Main Index
Main Index
50
Main Index
Launch MSC Nastran OpenFSI-AcuSolve Simulation
Launch MSC Nastran OpenFSI-AcuSolve Simulation
Main Index
Launch MSC Nastran OpenFSI-MpCCI Simulation (for Fluent & StarCD)
52
Launch MSC Nastran OpenFSI-MpCCI Simulation (for
Fluent & StarCD)
Main Index
Examine the Results Using SimXpert
Main Index
54
Main Index
Chapter 5: OpenMDO
5
OpenMDO
Introduction 2
Run MSC Nastran OpenMDO Optimization 6
Creating an OpenMDO SCA service 9
Appendix 13
Reference 16
Main Index
Introduction
2
Introduction
MSC Nastran SOL 200 is used for design optimization of an objective function based on design variables
and subject to performance constraints and side constraints. Design sensitivity analysis computes the
rates of change of structural responses with respect to changes in design parameters. These design
parameters, or design variables, can be such things as shell thicknesses, beam dimensions, hole radii,
material properties and so on. The responses can be any direct response (DRESP1) supported by SOL
200, plus any synthesized response (DRESP2) which can be a complex combination of direct or
synthesized responses. There is also the capability for the user to create his own responses (DRESP3) via
an external program that links to MSC Nastran.
The design variables, responses, constraints, and sensitivities can be submitted to an optimization
algorithm which can search for an improved design. There are many optimization algorithms that have
been written over the years. In MSC Nastran, there are two MSC proprietary general purpose optimizers:
MSCADS and IPOPT. To provide more options and flexibility to the users, MSC has created a Simulation
Component Architecture (SCA) plugin to allow users to access other commercially available
optimization codes or their own general or specific purpose optimization codes. MSC refers to this SCA
plugin capability as OpenMDO
TM
.
The OpenMDO
TM
interface provides a convenient method to use the power of the MSC Nastran Solver,
the MSC Nastran design sensitivity calculations, and approximation technology with an alternative
optimizer. This can benefit both commercial users and researchers who may want to use or test their own
optimizers. OpenMDO
TM
also provides a method for users to plugin other commercial optimizers.
MSC has partnered with VRND (Vanderplaats Research & Development, Inc) who have agreed to
implement the published OpenMDO API (the Application Programming Interface). These interfaces are
delivered in the form of a library and SCA catalog entry that enables the communication between MSC
Nastran and VRND's DOT/BIGDOT.
OpenMDO
TM
is based on the Simulation Component Architecture (SCA) framework (Ref 1). It allows
MSC Nastran SOL200 (Optimization Solution) to communicate with an external optimizer code to send
the objective, constraint functions, and their gradients to the optimizer and get a new design from the
optimizer. MSC Nastran optimization loop with SCA OpenMDO component is shown in Figure 5-1.
MSC Nastran loads the SCA external optimizer component in DOPR1 module (pre-optimization
module) and unloads the SCA external optimizer component in DOM12 module (pos-optimization
module.
In DOM9 (Design Optimization Module), the external optimizer is used to solve a SOL200
approximation problem. MSC Nastran employs a number of techniques, collectively referred to as
Approximation Concepts, to make design optimization possible for large finite element models. Design
variable linking, reduced basis vectors, constraint screening, load case deletion, and the approximate
model are discussed in Ref 2. These approximation concepts all play a role in reducing the cost of the
design task. MSC / MSC Nastran uses formal approximations (such as Taylor Series expansion) to avoid
the high cost associated with repeated finite element analyses during design optimization. As shown in
Figure 5-2, the optimizer interacts with the approximate model when it requires information. Given a set
of design variables, the optimizer needs information on the function values (the value of the objective
Main Index
3 Chapter 5: OpenMDO
Introduction
and the values of the retained constraints) and the gradient values (gradient of the objective with respect
to the design variables and the gradient of the active constraints with respect to the design variables).
First, SOL200 calls OpenMDO memory estimate function to allocate memory and initializes optimizer
control parameters, arrays, and work arrays. SOL200 provides some default values to OpenMDO
optimizer control parameters that are discussed in Section II. Then, SOL200 calls the external optimizer
and the external optimizer returns information parameter INFO, error flag ERROR=IPRM(18), and
NGT=IPRM(20) (number of critical constraints) to DOM9 to perform function or gradient evaluations or
terminate shown in Figure 5-3.
Figure 5-1 Flow Chart of MSC Nastran with External Optimizers
Main Index
Introduction
4
Figure 5-2 Optimizer Role in MSC Nastran Optimization
Since DOT/BIGDOT is a major optimizer and widely used in Auto and Aerospace industry, MSC
Nastran OpenMDO uses the ALLDOT (DOT/BIGDOT interface) calling statement as our OpenMDO
API with minor modification.
Main Index
Introduction
Figure 5-3 The Interaction Between SOL200 DOM9 and External Optimizers
To run an OpenMDO optimization the following software components are required:
MSC Nastran 2011 (or later).
An OpenMDO SCA component with an external optimizer
OpenMDO SCA components can be of two types:
1. Prebuilt components used with certain commercial optimizers.
2. User defined SCA components built with the OpenMDO software development kit (SDK).
Main Index
Run MSC Nastran OpenMDO Optimization
6
OpenMDO Input Deck
For a user to run an optimization SOL200 job by using the OpenMDO interface, a SCA service must be
defined in the file management section in the Nastran input file by a CONNECT Service statement. The
connection between the SCA service and SOL200 is done by defining an optimizer code OPTCOD on
the DOPTPRM bulk data entry which is tagged with the SCA service identifier in the CONNECT Service
statement. For example as below, input file Connect Service statement references an external OpenMDO
service called 'ExternalOptimizer.OpenMDO'. The word "ALLDOT" (Optimizer code in DOPTPRM and
service identifier in CONNECT Service statement) connects SOL200 with
'ExternalOptimizer.OpenMDO' ser.
Running MSC Nastran
To run an MSC Nastran OpenMDO job, a SCA service catalog, which contains references to available
SCA services components, and an associated library path, pointing to the interface functions library, must
be specified. A resource directory may also be specified. This is done by setting environment variables
as follows:
setenv SCA_SERVICE_CATALOG
$SCAPATH/Apps/res/SCAServiceCatalog.xml
setenv SCA_LIBRARY_PATH $SCAPATH/Apps/LX8664/lib/
setenv SCA_RESOURCE_DIR $SCAPATH/Apps/res/
if a csh shell is used. Here $SCAPATH refers to the path where the SCA service components are installed
on the system. For a Bourne shell, like ksh or bash, the environment variables are defined as:
export SCA_SERVICE
CATALOG=$SCAPATH/Apps/res/SCAServiceCatalog.xml
export SCA_LIBRARY PATH=$SCAPATH/Apps/LX8664/lib/
export SCA_RESOURCE DIR=$SCAPATH/Apps/res/
File management CONNECT SERVICE ALLDOT
ExternalOptimizer.OpenMD
O
Executive control
SOL200
END
Case Control
DESOBJ = 10
DESSUB=20
SUBCASE 1
ANALYSIS = STATICS
.
Bulk data
BEGIN BULK
.
DOPTPRM OPTCOD ALLDOT METHOD 1
.
Main Index
To execute Nastran with the input deck model.dat simply enter the following line:
nastran model.dat
Example: Intermediate Complexity Wing (ICWSE01.dat)
This intermediate complexity wing shown in Figure 5-4 was solved using MSCADS, IPOPT in MD
Nastran 2010 Release Guide. In this Section, ALLDOT (DOT and BIGDOT) is used as an external
optimizer to solve this problem.
Figure 5-4 Intermediate Complexity Wing Model
This composite structure is modeled with 62 CQUAD4 elements, 55 CSHEAR elements, 39 CROD
elements, and 39 CONM2 elements. Two static load cases are imposed along with a normal modes
subcase. The objective is to minimize the weight. There are 153 sizing design variables and 414 stress
and failure index constraints and a lower and upper bounds on the first fundamental frequency. To use
ALLDOT, a parameter OPTCOD=ALLDOT is added on the Bulk Data Entry DOPTPRM:
CONNECT SERVICE ALLDOT ALLDOT.OpenMDO
...
...
...
DOPTPRM APRCOD 2 DESMAX 30 DELP 0.50 DPMIN 0.001
delx 0.49 p1 1 p2 12 OPTCOD ALLDOT
METHOD 1
METHOD=1 is the DOT's MMFD method, METHOD=4 is the BIGDOT algorithm.
Table 5-1 shows the DOT and BIGDOT results for this example and all results are comparable.
Main Index
8
Table 5-1 Intermediate Complexity Wing Optimization Results
Initial Value
Optimum
DOT (MMFD)
Optimum
BIGDOT
Optimum
Ipopt
Optimum
MSCADS
(MMFD)
Objective 1.6892+2 1.9893+2 1.9570+2 1.9282+2 1.9624+2
Max Con 5.8425+2 1.4267-03 1.5355-04 5.5370-03 2.7015-03
# Cycles 14 20 20 14
Main Index
Creating an OpenMDO SCA service
Build tools
To create a user defined OpenMDOSCA service, the SDK provided with the MSC Nastran distribution is
used. In addition, a C/C++ compiler (and a Fortran compiler if external optimizer is written in Fortran)
is needed to compile the source code. The SCA services are built using the scons tools included in the
SDK distribution. It is recommended that users read Chapter 1 User Defined Subroutines to understand
the following :
Creating the desired implementation for the User Defined Services in the form of dynamic-link
libraries.
Defining the location of the user defined service, service catalogue, and service resource
directory.
The quick start guide (Appendix A) also describes how to compile and run the user defined services
examples delivered with MSC Nastran by utilizing the MSC Software Development Kit (SDK) on
Windows. ). The implementation examples consist of ready-to-compile source and one or more models
that utilize the user service. The implementation examples include OpenMDO.
After installing the SDK, make sure that the SDK Tools directory is in your path:
PATH[install_path]\Tools
Then set the following environment variables to point to the install directory, e.g:
setenv SCONS_TOOLS $SDKPATH/Tools
setenv APPS_SYSTEM $SDKPATH/SCAKernel
if a csh shell is used. Here $SDKPATH is replaced by the path to the SDK installation. For a Bourne
shell, like sh or bash, the environment variables are defined as:
export SCONS_TOOLS=$SDKPATH /Tools
export AAPS_SYSTEM=$SDKPATH /SCAKernel
The environment variables C and CXX specify the C and C++ compiler paths, and the environment
variable CCOMPILER specifies the vendor, which can be intel or gcc.
Build an Example myOpenMDO
To build the implementation example myOpenMDO delivered with MSC Nastran, the following files are
needed in the source directory:
myOpenMDO.cdl
myOpenMDO.cpp
myOpenMDO.h
myOpenMDO.sdl
SConscript
Main Index
10
All these files are already created as a simple OpenMDO example with a dummy optimizer located in
$NASTPATH/md<version>/nast/services/Implementations/OpenMDO.
Here $NASTPATH is the path to the MSC Nastran installation. An interface definition file
OpenMDO.idl is located in
$NASTPATH/md<version>/nast/sdk/idl/SCA/MDSolver/Util/OpenMDO. There is a
dummy optimizer Fortran source code alldotd.F (alldots.F) and dotstrd.F (dotstrs.F)
in directory
$NASTPATH/md<version>/nast/services/Implementations/OpenMDO/double or
single for a double or single precision OpenMDO build.
Here is the procedure to build the OpenMDO SCA components:
1. Change directory to the source code root directory:
$NASTPATH/md<version>/nast/services
2. Build the SCA component from the source code root directory by simply entering Scons (use a
full path $SDKPATH/Tools/scons if not found)
If the SConopts.user file does not exist in the home directory or if the paths are not defined in that
file, the SCA_OBJECT and APPS_LOCAL paths must be specified when running scons (see Build
Environment and Building the Service in Chapter 1). See the FAQ questions in the Quick Start Guide
for User Defined Services (App. A) for advanced usage of the scons command to utilize, for example,
alternate compilers or non-standard compiler installation paths.
The scons command should create the OpenMDO SCA component files, including the service catalog
file SCAServiceCatalog.xml in the Apps/res directory and the library libopenMDO.so in
the Apps/LX8664/lib for a Linux x8664 system. The library name and directory name will depend
on the platform where the SCA component is built. The location must be consistent with the path defined
by the environment variables SCA_SERVICE_CATALOG, SCA_LIBRARY_PATH and
SCA_RESOURCE _DIR when executing MSC Nastran.
To run the example job dsgopenmdo.dat, change the directory to the OpenMDO model directory
$NASTPATH /md<version>/nast/services/Implementations/OpenMDO/model and
set three environment variables SCA_SERVICE_CATALOG, SCA_LIBRARY_PATH and
SCA_RESOURCE_DIR (see Run MSC Nastran OpenMDO Optimization in this Chapter 5). Then enter
nastran dsgopenmdo.dat (use a full path if the command nastran not
found)
Once the run is completed, the user can find the following print in either dsgopenmdo.log or
dsgopenmdo.f06 (depending on the platform):
******************************
THIS IS A DUMMY OPTIMIZER
******************************
Since this is a dummy optimizer example, the optimization job stops at the first design cycle with the
final objective= 4.828427E+00 as the initial design in dsgopenmdo.f06.
Main Index
Note that if the user wants to support his own optimizer written in Fortran, the user can use this
myOpenMDO implementation example by adding the optimizer source code to the directory
~/OpenMDO/double (for double precision code) and ~/OpenMDO/single (for single precision).
To include a static library, add the following line to the ~/OpenMDO/SConscript file:
env.AddLinkLibrary("$LIBPATH/lib/libMyLib.a")
where $LIBPATH is the path to the install location of the library. To include a dynamic library, add the
following line to the ~/OPenMDO/SConscript file:
env.AddLinkSharedLibrary("$LIBPATH/lib/libMyLib.so")
Building a New OpenMDO Service from Scratch
The OpenMDO.idl and SConscript files that are provided with the SDK, are normally used to make
all OpenMDO services, so that only the files with root name myOpenMDO need to be recreated (or
created with a different name) if a new service is created from scratch. To make a new OpenMDO
component from scratch, use the following procedure:
1. Create a new service definition file myOpenMDO.sdl
A different name can be used if desired (but the extension should be .sdl). The document [3]
provides a tutorial on how an interface definition file (an .idl file) is created from scratch, along
with the creation of the service definition (.sdl) and component definition (.cdl) files. Here, the
interface definition file OpenMDO.idl is already provided and the service and component
definition files provide the interface for only one component, so the content in those files is
straightforward (see Service Definition Language file and Component Definition Language File
in the document [3]). An overview of the interface definition and implementation of the
OpenMDO methods is given the Appendix of this chapter.
2. Create the skeleton code files myOpenMDO.cpp and myOpenMDO.h.
As mentioned above, the interface for the OpenMDO SCA component is defined in the
OpenMDO.idl file and provides the Application Programming Interface (API) for implementing
the external optimizer code connecting to the MSC Nastran SOL200.
The interface has the following two functions (methods)
Estimate memory (storage calculations) for working arrays
Run the external optimizer to solve the optimization problem.
To generate the skeleton code where the service methods are implemented, enter:
genskeleton myOpenMDO.sdl
This command will create the skeleton code files myOpenMDO.cpp and myOpenMDO.h, based on the
OpenMDO.idl file within the name space provided in myOpenMDO.sdl. The header file
myOpenMDO.h contains the declarations for the OpenMDO service 'myOpenMDO'. The service
implementation file myOpenMDO.cpp contains a constructor and a destructor for the service object,
along with prototypes for the OpenMDO service methods that need to be populated with source code.
Main Index
12
3. Implement the source code in the myOpenMDO.cpp and myOpenMDO.h skeleton files.
Major code work is required for users to link the myOpenMDO.cpp with the external optimizer
(see MD 2011.1 Release Guide or MSC Nastran Design Sensitivity and Optimization User's
Guide for the detail).
4. Create a new component definition file myOpenMDO.cdl
5. Build the SCA component from the source code root directory using scons.
Alternatively, it is possible to only build the OpenMDO SCA component as follows:
1. Locate the OpenMDO.idl file and copy to the source directory.
2. Create a new myOpenMDO.sdl file.
3. Use the executable genskeleton to create skeletons for myOpenMDO.cpp and myOpenMDO.h.
4. Implement the source code in the myOpenMDO.cpp and myOpenMDO.h skeleton files.
5. Create a new myOpenMDO.cdl file.
6. Build the SCA component from the OpenMDO source code directory by entering scons --qb4.
See Run time errors and debugging, 36 for possible run time errors and debugging options.
Main Index
Appendix
Appendix
Interface Definition Language file
The IDL file used to build a SCA service connecting to the OpenMDO interface has the following form
#ifndef SCA_MDSOLVER_UTIL_OPENMDO_IDL_INCLUDED
#define SCA_MDSOLVER_UTIL_OPENMDO_IDL_INCLUDED
#include "SCA/Service.idl"
module SCA { module MDSolver { module Util { module OpenMDO {
typedef SCAInt32 SCAInt32StaticArray[];
typedef SCAInt64 SCAInt64StaticArray[];
typedef SCAReal64 SCAReal64StaticArray[];
interface SCAIMDSolverOpenMDO : SCAIService
{
/// OpenMDO.ldl is used to define an API for mathematical
programming problems
/// in MSC Nastran SOL200.
///
/// A general formulation of structural optimization problems can
be stated as follows
///
/// minimize f(X)
/// s.t. Gj(X) <= 0.0 j = 1, ..., m
/// xl(i) <= x(i) <= xu(i), i = 1, ,,,, n
///
/// where f(X) is the objective function of design variables X,
Gj(X) is the constraint,
/// and m is the number of inequality constraints. The design
variable X has lower bound XL
/// and upper bound XU. n is number of design variables.
/// Equality constraints are seldom true for engineering design.
MSC Nastran SOL200 does not
/// directly deal with equality constraints. Instead, if such
equality constraints are needed,
/// it is only necessary to add additional inequality constraints
of the form
///
/// Gk(X) >= 0.0
///
/// In other words, two equal and opposite inequality constraints
will force the function to
/// become an equality. Therefore, OpenMDO will consider only
inequality constraints.
///
/// MSC Nastran first calls exteranl optimizer (EstimateMemory) to
estimate required memenory,
/// initialize parameter/array and allocate memory. Then, calls
optimizer (RunOptimizer) to
/// solve the problem.
Main Index
Appendix
14
///
/// Here, OpenMDO suppors double precision
EstimateMemory_32/RunOptimizer_32,
/// and single precision (PTR64)
EstimateMemory_64/RunOptimizer_64
///

SCAResult RunOptimizer_32
(
inout SCAInt32 Info,
in SCAInt32 OptimizationMethod,
in SCAInt32 PrintControl,
in SCAInt32 NumberOfDesignVariable,
in SCAInt32 NumberOfConstraints,
inout SCAReal64StaticArray DesignVariable,
in SCAReal64StaticArray LowerBoundDesignVariable,
in SCAReal64StaticArray UpperBoundDesignVariable,
inout SCAReal64 Objective,
in SCAInt32 MinimumOrMaximum,
inout SCAReal64StaticArray Constraint,
inout SCAReal64StaticArray RealOptControlPar,
inout SCAInt32StaticArray IntegerOptControlPar,
inout SCAReal64StaticArray RealWorkArrayWK,
in SCAInt32 SizeofWK,
inout SCAInt32StaticArray IntegerWorkArrayIWK,
in SCAInt32 SizeofIWK,
inout SCAInt32StaticArray IntegerOptionArrayIOA,
in SCAInt32 SizeofIOA,
inout SCAReal64StaticArray RealOptionArrayROA,
in SCAInt32 SizeofROA);
SCAResult RunOptimizer_64
(
inout SCAInt64 Info,
in SCAInt64 PrintControl,
in SCAInt64 NumberOfDesignVariable,
in SCAInt64 NumberOfConstraints,
inout SCAReal64StaticArray DesignVariable,
inout SCAReal64 Objective,
in SCAInt64 MinimumOrMaximum,
inout SCAReal64StaticArray Constraint,
inout SCAReal64StaticArray RealOptControlPar,
inout SCAInt64StaticArray IntegerOptControlPar,
inout SCAReal64StaticArray RealWorkArrayWK,
in SCAInt64 SizeofWK,
inout SCAInt64StaticArray IntegerWorkArrayIWK,
in SCAInt64 SizeofIWK,
inout SCAInt64StaticArray IntegerOptionArrayIOA,
in SCAInt64 SizeofIOA,
inout SCAReal64StaticArray RealOptionArrayROA,
in SCAInt64 SizeofROA);
Main Index
Appendix
///
/// Calculate Computer Memeory Requirements
///
SCAResult EstimateMemory_32
(
in SCAInt32 NumberofDesignVariable,
in SCAInt32 NumberofConstraint,
out SCAInt32 MinimumDimWk,
out SCAInt32 DesiredDimWk,
out SCAInt32 MaximumDimWk,
out SCAInt32 DesiredDimIWk,
out SCAInt32 ExtraSpace,
inout SCAInt32 NumberOfCritialConstraint,
inout SCAInt32 SizeofIOA,
inout SCAInt32 SizeofROA,
in SCAInt32 MaximumInteger,
out SCAInt32 MemoryErrorFlag);
SCAResult EstimateMemory_64
(
in SCAInt64 NumberofDesignVariable,
in SCAInt64 NumberofConstraint,
out SCAInt64 MinimumDimWk,
out SCAInt64 DesiredDimWk,
out SCAInt64 MaximumDimWk,
out SCAInt64 DesiredDimIWk,
out SCAInt64 ExtraSpace,
inout SCAInt64 NumberOfCritialConstraint,
inout SCAInt64 SizeofIOA,
inout SCAInt64 SizeofROA,
in SCAInt64 MaximumInteger,
out SCAInt64 MemoryErrorFlag);
};
}; }; }; };
#endif
Main Index
Reference
16
Reference
1. MSC Nastran 2012 - SCA Framework User's Guide (DEV).
2. MSC Nastran 2012 Design Sensitivity and Optimization User's Guide, The MSC Software
Corporation, 2010.
3. MSC Nastran 2012 Quick Reference Guide, The MSC Software Corporation.
4. MD Nastran 2010.2 Release Guide, The MSC Software Corporation, 2010.
5. DOT User's Guide, Version 5.X, Vanderplaats Research & Development, Inc., 2001.
Main Index
Ap. A: Quick Start Guide for User Defined Services
A
Quick Start Guide for User
Defined Services
Introduction
MSC SDK Delivery Contents
Services Implementation Examples
Supported Operating Systems and Compilers
Compiling User Defined Services
Defining the path to User Defined Service
Pointing to a User Defined Services from MSC Nastran
Running MSC Nastran with a User Defined Service
SDK User Services on other Operating Systems
Errors Messages and Diagnostics
FAQ
Main Index
Introduction
18
Introduction
This quick start guide describes how to compile and run the user defined services examples delivered
with MSC Nastran by utilizing the MSC Software Development Kit (SDK). The implementations
examples consist of ready-to-compile source to build the services. The examples include one or more
models that utilize the user service. The services must be built and appropriate environment variable set
to locate them before attempting to run the models.
Once youre able to build and run the examples in the MSC Nastran delivery, please refer to the related
documents at the end for more information on how to create your own user defined services.
Main Index
19 Ap. A: Quick Start Guide for User Defined Services
The MSC Software Development Kit (SDK) is a downloadable product that provides the SCA tools
required to build services.
[install_path]\SDK\<version>\
| -- Tools
| -- SCAKernel
| -- Doc
After installing the SDK, make sure that the Tools directory is in your path:
PATH[install_path]\MSC\<version>\Tools
Main Index
20
Implementation examples are delivered as part of MSC Nastran. These services need to be built using
the tools in the SDK before they can be referenced from the MSC Nastran input files. The delivery
structure consists of:
[install_path]\MD_Nastran\<version>\md<version>\nast
| -- services
! | -- Implementations
! | -- Contact
! | -- Elements
! | -- Materials
! | -- archives
! | -- include
! | -- Models
! | -- src
! | -- OpenFSI
! | -- Model
! | -- OpenMDO
! | -- Model
! | -- <more services>
! | -- SConstruct
! | -- SConopts
! | -- SConscript
Main Index
User defined services must be built only on supported operating systems and compilers. Although MSC
Nastran may run on unsupported platforms, generation of services typically requires strict adherence to
the supported platforms and compilers.
Below is the list of supported operating systems and compiler versions for the MSC Nastran 2012 release:
Table A-1 Supported Operating Systems and Compilers
* 92453-07 linker dld is required.
** OS-Core. CORE-64SLIB, PHSS_28871.CORE-64SLIB
must be installed so the command:
what /usr/lib/pa20-64/dld.sl Displays:
PA64 B.11.66 PBO 080711
The Fortran compiler (e.g., Intel 10.1.024) may not the latest version available on the vendor download
site. See the FAQ section below for tips on how to download prior compiler versions.
Platform
Windows 32
and 64
Linux 32
and 64 IBM AIX HP-UX IA64
HP-UX
PA-RISC
Sun, Sparc
and
x86-64
Operating
System
Windows 7 RHEL 5.4
SuSe Linux 11
AIX 5.3.7.0 HPUX 11.23* HPUX
11.11**
Solaris 5.10
Fortran
Compilers
Intel Fortran
compiler 12.0
Intel Fortran
Compiler 12.0
XLF 11.1.0.4 F90 3.1 F90 3.1 F90 8.4
C/C++
Compilers
Microsoft
Visual Studio
2010 C/C++
Intel C/C++
Compiler 12.0
XLC 9.0.0.3 A.06.02 B.11.11.16 CC 5.10
Main Index
22
You can compile all the services in the services examples folder at one time or specify selected targets.
The steps below shown how to compile the services with scons:
1. Open a command window
Start Run Open: cmd
2. change directory to the \md<version>\nast\services folder under the MSC Nastran installation
3. check to make sure scons points to the Tools directory
4. issue the scons command to compile all the examples: > scons
(use full path if not found)
5. If there are existing services, you should clear them out with: >scons -c
6. To build only specific services, provide the targets as arguments, e.g., > scons [targets]
An illustration of the steps is shown below.
The output from a successful compilation is illustrated below.
scons: Reading SConscript files ...
Processing Source tree option file
C:\MSC.Software\MSC_SDK\MDr4Alpha2\Examples\SConopts
Using version 8.0 of Microsoft C++
Using version 10.1.024 of Intel Fortran
Build Type = OPT on WINNT
Source = C:\MSC.Software\MSC_SDK\MDr4Alpha2\Examples
Object =
C:\MSC.Software\MSC_SDK\MDr4Alpha2\Examples\WINNT_EXAMPLES_OPT
Apps Local = C:\MSC.Software\MSC_SDK\MDr4Alpha2\Examples\Apps
Apps System = C:\MSC.Software\MSC_SDK\MDr4Alpha2\SCAKernel
Tools System = C:\MSC.Software\MSC_SDK\MDr4Alpha2\Tools
34 Source directories processed
scons: done reading SConscript files.
scons: Building targets ...
""
(deleted for clarity)
""
scons: done building targets.
Main Index
See the FAQ questions below for advance usage of the scons command to utilize, for example, alternate
compilers or non-standard compiler installation paths.
Main Index
24
A successful compilation should create an Apps folder with the following structure.
[install_path]\MD_Nastran\<version>\md<version>\nast
| -- services
| | -- Apps
! | -- res
! -- SCAServiceCatalog.xml
! | -- WINNT
! | -- lib
! -- MySrv1.dll
! -- MySrv2.dll
! | -- SCA\MDSolver\Obj\Uds
! -- Materials.dll
! -- Contact.dll
! | -- Test
! -- OpenFSI.dll
The libraries (*.dll or .so) that appear under lib and its subdirectories represent the service modules
created from the scons build. The SCAServiceCatalog.xml contains a catalog of all the services created
by the build session. Note that the libraries may appear directly under /lib or under various directory
levels below /lib. For purposes of pointing to them, the environment variables should only point to /lib.
In order to use the above services, three environment variables have to be set:
SCA_LIBRARY_PATH - points to location of the user service libraries, e.g.,
[install_path]\....\nast\services\Apps\WINNT\lib
SCA_SERVICE_CATALOG - points to location of the SCA service catalog, e.g.,
[install_path]\....\nast\services\Apps\res\SCAServiceCatalog.xml
SCA_RESOURCE_DIR - points to location of SCA resource directory, e.g.,
[install_path]\....\nast\services\Apps\res
Multiple paths can be listed for the environment variables (separated by a ; on Windows) and will be
search in the order they appear.
Main Index
Each example implementation in the MSC Nastran delivery contains one or more MSC Nastran models
that utilize the service. The service is referenced through the CONNECT SERVICE entry in the MSC
Nastran input file. The available services are cataloged in the SCAServiceCatalog.xml file.
A sample of the SCAServiceCatalog.xml created by the above build session is illustrated below.
<?xml version="1.0" ?>
<SCA>
<component language="C++" library="SCA/MDSolver/Obj/Uds/Contact"
name="SCA.MDSolver.Obj.Uds.Contact">
<service name="SCA.MDSolver.Obj.Uds.Contact"/>
</component>
(deleted for clarity)
<component language="C++" library="Test/OpenFSI"
name="Test.OpenFSI">
<service name="myOpenFSI"/>
</component>
</SCA>
The service name specified in the MSC Nastran input file must match exactly (case sensitive) the service
name that appears in the SCA Service Catalog above. The illustrations below show this for two of the
input files included in the MSC Nastran services directory.
\services\Implementations\Contact\models\nufric.dat
The input file for this user defined contact model contains the following connect service entry:
connect service contact 'SCA.MDSolver.Obj.Uds.Contact'
\services\Implementations\OpenFSI\model\fsi_sdk1.dat
The input file for this OpenFSI model contains the following connect service entry:
CONNECT SERVICE ACUCFD 'myOpenFSI'
Note: Multiple Connect Service entries are permitted in the MSC Nastran input file.
Main Index
26
Once the service has been created, launch MSC Nastran 2011.2 as usual specifying the model names
under the MSC Nastran services examples folder. Note that user defined services require that IFPStar be
enabled:
Input File Name: <filename>.dat
Nastran Keywords: IFPSTAR=yes
At run time, MSC Nastran will search for the service by following the environment paths to locate the
SCA Service Catalog and the corresponding service library.
Information on the SCA service success or failure of the SCA service connection can be found in the
MSC Nastran .f06 and .log files. See below for various errors and diagnosis.
Main Index
There are a few differences in the above procedure for Windows64 and Linux.
1. On Windows 64-bit, the libraries will appear under WIN8664 instead of WINNT. Accordingly,
the environment variable pointing to the library should be:
SCA_LIBRARY_PATH [install_path]\...\nast\services\Apps\WIN8664\lib
2. On Linux, the libraries built will appear under LINUX or Unix OS label, e.g.,:
SCA_LIBRARY_PATH [install_path]\...\nast\services\Apps\LX8664\lib
Main Index
28
Table A-2 shows some typical causes for run time errors.
Table A-2 Run Time Errors
Error Message Possible Cause and Resolution
MSC Nastran F06 file error message:
SCA ServiceName service initialization failed.
1. Check that the service name is not misspelled in
the MSC Nastran input file Connect Service
entry.
a. Service name is case sensitive.
b. Make sure you only have a single space as
separator in the Connect Service entry; e.g.,
CONNECT SERVICE scafsi myOpenFSI
2. Check that the SCA_LIBRARY_PATH points
to the service library /lib directory.
a. Note that if the library is specified to be
located in a subdirectory to /lib, say /lib/Test,
(it will say library="Test/OpenFSI" in the
SCAServiceCatalog.xml file), the specified
path should still point to /lib.
3. Check that SCA SERVICE CATALOG points to
the applicable SCA Service Catalog
*** SYSTEM FATAL MESSAGE 305 (IFPDRV)
IFP MODULE CANNOT OPEN GINO FILE 0
USER FATAL MESSAGE 9002 (IFPS)
Input file entries require IFPStar. Note that IFPStar is not
the default in MSC Nastran 2011.2.
1. Insert NASTRAN IFPSTAR=yes into the input
file
2. specify IFPSTAR=yes on the Nastran command
line or in an rcfile
Run time crash:
Analysis.exe - Entry Point Not Found
The service was created with a kernel that is not
compatible with this MSC Nastran version.
a. If you have the source, rebuild the service
with the MSC SDK corresponding to the
MSC Nastran release
b. Obtain a compatible version of the service
from the vendor
Main Index
Table A-3 shows some typical Scons build errors.
Table A-3 Scons Build Errors
MSC Nastran runs on an unsupported OS (e.g., Linux-
XYZ) without SCA service but issues this error when
running with a service.
*** USER FATAL MESSAGE 116 (QueryAccess)
SCA services must be built only on the supported
operating systems listed in Table 1.
1. Although MSC Nastran may run on unsupported
platforms, generation of services typically
requires strict adherence to the supported
platforms and compilers.
A service works fine on a Windows machine where the
service was built, but will not run on a different windows
machine.
Remove security patch KB971090 under Add or
Remove Programs and rebuild the service.
Message during Scons compilation:
Processing Source tree option file
C:\MSC.Software\MSC_SDK\MDr4Alpha2\Examples\S
Conopts
Warning: MSVS verions 8.0 not found - using version 9.0
instead
IndexError: list index out of range:
Scons is using Version 9.0 of Microsoft compiler. The
official supported compiler version is version 8.0 that
corresponds to MSVS 2005. We do not support MSVS
2007 or beyond.
Main Index
30
Situation
User set the compiler settings to:
export C=/usr/bin/gcc
export CXX=usr/bin/gcc
export CCOMPILER=gcc

The error receive is the following:
Warning: Intel C++ compiler version 10.1.017 not found -
using 0 instead
Warning: Intel Fortran compiler version 10.1.017 not
found - using 0 instead
Error: Could not locate the Intel C++ compiler installation
GCC compilers are not supported. See table 1 for
supported compilers.
Installed "Intel Visual Fortran Compiler Professional
Edition for Windows". The intel download site only has
11.x.xxx
Warning: Intel Fortran compiler version 10.1.024 not found
- using 0 instead
Using version 8.0 of Microsoft C++
KeyError: 'SHFORTRANCOM':
SCA services are particular about the compiler version. It
does not support Intel 11.x.xxx.
You can download prior compiler versions. See
instructions on:
http://software.intel.com/en-us/articles/older-version-
product/
Main Index
FAQ
FAQ
1. Can I run a service built with Windows 32 with MSC Nastran installed on Windows 64?
User defined services must be compatible with the MSC Nastran platform version. In the case of
Windows 64-bit system, it is possible to force MSC Nastran to run in 32-bit to be compatible with
a service build on a 32-bit system. To force MSC Nastran to run in 32-bit mode, use:
keywords: arch=32
2. Can I use a different version of Intel compiler, other than the default version?
You can use the following construction variables:
INTEL_CXX_VERSION
INTEL_FORTRAN_VERSION
3. Intel doesn't sell 10.1 anymore. What should I do?
If you have a valid license for current compiler version (11.1.xxx), you can login to Intel support
web site and download the older compiler versions (10.1.017). Note that your existing license
should work for the older compiler. Instructions on how to download prior versions can be found
at:
http://software.intel.com/en-us/articles/older-version-product/
4. How do I set the path to compiler locations, if they are not installed at the default locations?
You can use a pair of construction variables to point to the path that your compilers are installed. These
are: INTEL_CXX_ROOT and INTEL_FORTRAN_ROOT. Note that PATH_TO_XXX_COMPILER
should point to the _parent_ directory of the bin directory for that particular compilers architecture
and version. For example:
> .
> | `-- C++
> | `-- 10.1.022
> | |-- Compiler
> | |-- Docs
> | |-- IA32 <- Variable INTEL_CXX_ROOT should point to here.
> | | |-- Bin
> | | | |-- 1033
5. Where do I find related documents on building my own services?
More details on building user services and examples of user defined applications can be found in
the following documents:
MSC Nastran 2012 - SCA Service Guide
MSC Nastran 2012 User Defined Services
MSC Nastran 2012 - Demonstration Problems Manual
Note: For the MSC Nastran 2010 version release, we do not support Intel compiler version
11.XX.YYY
Main Index
FAQ
32
Main Index
Ap. B: Compatibility Matrix
B
Compatibility Matrix
Product Compatibility Matrix

Main Index
34
This table shows what version of the SDK is compatible with which version of MSC Nastran or
SimManager.
SDK MSC Nastran SimManager
2012 2012 2012
2010.1.3
2011
2010.1.3
2010
X
2010.1.2 2010 2010
2010 X 2010
Main Index

MSC Nastran 2012 User Defined Services

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

MSC Nastran 2012 User Defined Services

Uploaded by

Copyright:

Available Formats

MSC Nastran 2012

User Defined Services

Supported User Defined Subroutines 4

Implementation with Templates 6

Implementation without Templates 7

Building the Service 10

Using the Service 12

User Defined Module Service UDMSRV 2

Memory management interface 5

Running an OpenFSI MSC Nastran simulation 11

Creating an OpenFSI SCA service 22

Launch SimXpert and Import the Structural Model 42

Define the Service for the Coupled Solution 43

Define the OpenFSI LBCs (Wettted Surfaces) 44

Define a Nonlinear Simulation 46

Launch MSC Nastran OpenFSI-AcuSolve Simulation 51

Launch MSC Nastran OpenFSI-MpCCI Simulation (for Fluent &

Examine the Results Using SimXpert 53

Run MSC Nastran OpenMDO Optimization 6

Creating an OpenMDO SCA service 9

MSC SDK Delivery Contents

Services Implementation Examples

Supported Operating Systems and Compilers

Compiling User Defined Services

Defining the path to User Defined Service

Pointing to a User Defined Services from MSC Nastran

Running MSC Nastran with a User Defined Service

SDK User Services on other Operating Systems

Errors Messages and Diagnostics

Product Compatibility Matrix

You might also like