MSC Nastran 2012 User Defined Services

MSC Nastran 2012

User Defined Services

Worldwide Webwww.mscsoftware.com

DisclaimerMSC.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

CorporateMSC.Software Corporation2 MacArthur PlaceSanta Ana, CA 92707Telephone: (800) 345-2078FAX: (714) 784-4056

EuropeMSC.Software GmbHAm Moosfeld 1381829 MunichGERMANYTelephone: (49) (89) 43 19 87 0Fax: (49) (89) 43 61 71 6

Asia PacificMSC.Software Japan Ltd.Shinjuku First West 8F23-7 Nishi Shinjuku1-Chome, Shinjuku-Ku Tokyo 160-0023, JAPANTelephone: 0120-924-832 (toll free, Japan only)Mobile phone: 03-6911-1222Fax: (81) (3)-6911-1201

C o n t e n t sUser Defined Services

1 User Defined Subroutines

Introduction 2

Overview 3

Supported User Defined Subroutines 4

Build Environment 5Path 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 15F06 Printing Routine 15DDOT 15GMADD 16GMPRD 16GMSUB 17GMTRA 17GTPRD 18Invert 3 x 3 Matrix 19MCPY 19PRINCV 20SCLA 21EXT_USELEM 21EXT_HYPELA2 27EXT_UELASTOMER 34EXT_ORIENT 41EXT_CRPLAW 44EXT_UFAIL 49


ii

EXT_UPROGFAIL 51EXT_MOTION 56EXT_UFRIC 60EXT_SEPFOR 63EXT_SEPSTR 66EXT_UBSQUEAL 68

2 User Defined Module Service UDMSRV

User Defined Module Service UDMSRV 2Introduction 2

Utility services 4

Memory management interface 5

Database access: 6

3 OpenFSI

Introduction 8

Running an OpenFSI MSC Nastran simulation 11OpenFSI input deck 11Running MSC Nastran 19A simple example model 19

Creating an OpenFSI SCA service 22Build tools and source files 22OpenFSI interface and implementation 23

Appendix 25Interface Definition Language file 25Service Definition Language file 33Component Definition Language file 34OpenFSI data flow 34Run 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

iiiContents

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 6OpenMDO Input Deck 6Running MSC Nastran 6

Creating an OpenMDO SCA service 9Build tools 9Build an Example myOpenMDO 9Building a New OpenMDO Service from Scratch 11

Appendix 13Interface 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


iv

Errors Messages and Diagnostics 28

FAQ 31

B Compatibility Matrix

Product Compatibility Matrix 34

Chapter 1: User Defined SubroutinesUser Defined Services User’s 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

User Defined Services User’s GuideIntroduction

2

IntroductionThe 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 Nastran’s 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.

3Chapter 1: User Defined SubroutinesOverview

OverviewThe 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}

User Defined Services User’s GuideSupported 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

5Chapter 1: User Defined SubroutinesBuild Environment

Build EnvironmentIn 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 Descriptionsmsc_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>'

User Defined Services User’s GuideImplementation with Templates

6

Implementation with TemplatesThe 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_uelastomer.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_uprogfail.F

7Chapter 1: User Defined SubroutinesImplementation without Templates

Implementation without TemplatesWithout 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, let’s 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)

User Defined Services User’s GuideImplementation without Templates

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 {

// ConstructorNlrsfd::Nlrsfd(SCAINlrsfdFactoryAccess* factoryAccess) : NlrsfdBase(factoryAccess){}

// DestructorNlrsfd::~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,

9Chapter 1: User Defined SubroutinesImplementation without Templates

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;}

}

User Defined Services User’s GuideBuilding the Service

10

Building the ServiceTo 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>

11Chapter 1: User Defined SubroutinesEnvironment Variables

Environment VariablesIn 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\libset SCA_SERVICE_CATALOG=<APPS_LOCAL>\res\SCAServiceCatalog.xmlset SCA_RESOURCE_DIR=<APPS_LOCAL>\res

Windows (64 bit):

set SCA_LIBRARY_PATH=<APPS_LOCAL>\WIN8664\libset SCA_SERVICE_CATALOG=<APPS_LOCAL>\res\SCAServiceCatalog.xmlset SCA_RESOURCE_DIR=<APPS_LOCAL>\res

Linux (32 bit):

set SCA_LIBRARY_PATH=<APPS_LOCAL>/LX86/libset SCA_SERVICE_CATALOG=<APPS_LOCAL>/res/SCAServiceCatalog.xmlset SCA_RESOURCE_DIR=<APPS_LOCAL>/res

Linux (64 bit):

set SCA_LIBRARY_PATH=<APPS_LOCAL>/LX8664/libset SCA_SERVICE_CATALOG=<APPS_LOCAL>/res/SCAServiceCatalog.xmlset SCA_RESOURCE_DIR=<APPS_LOCAL>/res

User Defined Services User’s GuideUsing the Service

12

Using the ServiceIn 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.

13Chapter 1: User Defined SubroutinesUsing 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

...

User Defined Services User’s GuideError Handling

14

Error HandlingThe 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).

15Chapter 1: User Defined SubroutinesUtility Routines

Utility Routines

F06 Printing RoutineThe 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 :: printf06integer :: 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.

User Defined Services User’s GuideUtility 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.


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:




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 = WT

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 = WT*X

Note: Matrices W and X are real*8 matrices.

Note: Matrices W, X, and Y are real*8 matrices.


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.


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.


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 user’s requirements are defined as follows:

Note: Matrix W and scalar C are real*8 variables.


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.


typedef SCAInt64 DynInt64[];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 DynReal64_2 dispt, in DynReal64_2 disp, in SCAInt64 ndi, in SCAInt64 nshear, in SCAInt64 ipass, in SCAInt64 nstats, in SCAInt64 ngenel,


24

in SCAInt64 intel, in DynReal64_2 coord, 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, in DynInt64 cidata );};

}; // 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,


& 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

integer, external :: printf06

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.


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.



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 {

typedef SCAInt32 DynInt32[];typedef SCAInt64 DynInt64[];typedef SCAReal64 DynReal64[];

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 tn=

t tn 1+=


28

typedef SCAReal64 DynReal64_2[][];

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 disp, in DynReal64_2 dispt, in DynReal64_2 coord, 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, in DynInt32 cidata );

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,


in DynInt64 kcus, in DynInt64 matus, in SCAInt64 ndi, in SCAInt64 nshear, in DynReal64_2 disp, in DynReal64_2 dispt, in DynReal64_2 coord, 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, in DynInt64 cidata );};

}; // 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,


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) :: len_idata, len_rdata, len_cdata 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(out) :: error_code

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


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 tn= t tn 1+=

t tn=

t tn 1+=


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.


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 ENDDOENDDO

Dij

i j -----------------=

D

Gi

Gi Dn 1+ D

n– ij j=

n n 1+ j


34

In this case, STRECHN1 stores the value of the squares of the stretches, and EIGVN1(I,J) stores the

Ith eigenvector component corresponding to the Jth 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 user’s 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 I1 I2 I3 =

W W 1 2 3 =

W Wdev I1 I2 U J +=

W Wdev 1 2 3 U J +=

I1 I2 I3 1 2 3 I1 I2 1 2 3

I1 J 2 3/– I1= I2 J 4 3/– I2= i J 1 3/– i= i 1 2 3 = J


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 Wdev I1 I2 =

W Wdev 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.


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, in DynInt32 cidata );

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,


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, in DynInt64 cidata );};

}; // 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) :: len_idata, len_rdata, len_cdata integer, intent(in) :: iflag, nn, nstats, isunit integer, intent(out) :: error_code 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


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


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

tn

tn 1+


40

Example:

To define a rubber material based on strain energy function (Mooney model):

W = C1 (I1-3) + C2(I2-3)

Foam Rubber

iflag = 1 iflag = 2 iflag = 3 iflag = 4 iflag =5 iflag =6

W1

W2

W3N/A N/A

W11

W22

W33N/A N/A

W12

W23N/A N/A

W31N/A N/A

dudjN/A N/A N/A N/A

du2djN/A N/A N/A N/A

WI1-------- W

1--------- W

I1

-------- W

1

--------- W

I1

-------- W

1

---------

WI2-------- W

2--------- W

I2

-------- W

2

--------- W

I2

-------- W

2

---------

WI3-------- W

3--------- W

3

--------- W

3

---------

2W

I12

----------- 2W

12

----------- 2W

I12

----------- 2 W

12

----------- 2W

I12

----------- 2 W

12

-----------

2W

I22

----------- 2W

22

----------- 2W

I22

----------- 2 W

22

----------- 2W

I22

----------- 2 W

22

-----------

2W

I32

----------- 2W

32

----------- 2 W

32

----------- 2 W

32

-----------

2WI1I2---------------- 2W

12------------------- 2W

I1I2

---------------- 2W

12

------------------- 2W

I1I2

---------------- 2W

12

-------------------

2WI2I3---------------- 2W

23------------------- 2W

23

------------------- 2W

23

-------------------

2WI3I1---------------- 2W

31------------------- 2W

31

------------------- 2W

31

-------------------

UJ------- U

J-------

2UJ 2---------- 2U

J 2----------


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, C1 ,C2

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.

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_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 {


42

module Uds {module Materials {module orient {

typedef SCAInt32 DynInt32[];typedef SCAInt64 DynInt64[];typedef SCAReal32 DynReal32[];typedef SCAReal64 DynReal64[];

typedef SCAInt32 DynInt32_2[][];typedef SCAInt64 DynInt64_2[][];typedef SCAReal32 DynReal32_2[][];typedef SCAReal64 DynReal64_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, in DynInt64 cidata);};

}; // 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,


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, & 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) :: nn, isunit, ncrd integer, intent(out) :: error_code

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'1v'2v'3

G11 G12 G13

G21 G22 G23

G31 G32 G33

v1

v2

v3

=


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.

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_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.

gji

· c f T t c p 1 2 etc =


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

1 2 etc.


46

in DynInt32 idata, in DynReal64 rdata, in DynInt32 cidata);

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, in DynInt64 cidata);};

}; // 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)


implicit none

integer, intent(in) :: len_idata, len_rdata, len_cdata integer, intent(in) :: m, nn, ndi, nshear, nstats, ncomp, isunit integer, intent(out) :: error_code 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 real(8), intent(in), dimension(nstats) :: dt, dtdl



end subroutine ext_crplaw


48

The simplest way to define a creep strain increment from a given rate law is to multiply by t, 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 (J2) 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 23---c

ijcij

1 2=

· c f e t c =

c t f etc =


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.

MATUDS defines the service name corresponding to the material, and the data (integer, real and 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 AB--- sinh=


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, & 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) :: nelem, nint, ndi, nshear, nstats, isunit integer, intent(in) :: ncomp integer, intent(out) :: error_code

integer, intent(in), dimension(2) :: kcus, matus real(8), intent(in), dimension(ncomp) :: stress, strain real(8), intent(out), dimension(2) :: failc real(8), intent(in), dimension(nstats) :: dt, dtdl



end subroutine ext_ufail


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)


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, in DynInt32 cidata);

SCAResult usrUprogfail_64( in SCAInt64 nelem, in SCAInt64 nint,


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, in DynInt64 cidata);};

}; // 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) :: len_idata, len_rdata, len_cdata integer, intent(in) :: nelem, nint, icrit, nstats, isunit, ncomp


54

integer, intent(out) :: ideact, error_code real(8), intent(in) :: time, timeinc

integer, intent(in), dimension(2) :: kcus, matus real(8), intent(in), dimension(ncomp) :: stress, strain real(8), intent(in), dimension(6) :: fi, redfac0 real(8), intent(out), dimension(6) :: redfac real(8), intent(in), dimension(nstats) :: dt, dtdl



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

11 22 33 12 23 13

11 22 33 12 23 13


The six components of redfac will be used for scaling the material moduli of an orthotropic material according to

The Poisson’s ratios are scaled the same way as the corresponding shear modulus.

For an isotropic material, the Young’s modulus is scaled with the smallest of the components of redfac and the shear modulus is calculated using the updated Young’s modulus and the Poisson’s 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

E11new

re d fac 1 E11orig=

E22new

re d fac 2 E22orig=

E33new

re d fac 3 E33orig=

G12new

re d fac 4 G12orig=

G23new

re d fac 5 G23orig=

G31new

re d fac 6 G31orig=


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 user’s 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.


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, in DynInt32 cidata );

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, in DynInt64 cidata );};

}; // motion}; // Contact}; // UDS}; // Obj}; // MDSolver}; // SCA


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, & len_rdata, len_cdata, error_code) implicit none

integer, intent(in) :: len_idata, len_rdata, len_cdata integer, intent(in) :: nsurf, inc, isunit, nsize, nsize_v integer, intent(out) :: error_code real(8), intent(in) :: time, dtime

real(8), intent(in), dimension(nsize) :: x, f real(8), intent(out), dimension(nsize_v) :: v


integer, external :: printf06 ! 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.


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


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 data (integer, real and characters) required in the user subroutine. It should look like the following for EXT_UFRIC application:

BCONUDS,bid,BCBODY,sname,UFRIC,

,INT,…

,REAL,…

,CHAR,…

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_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


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, in DynInt32 cidata );

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, in DynInt64 cidata );};

}; // 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,


62

& len_vrel, len_idata, len_rdata, len_cdata, & error_code) implicit none

integer, intent(in) :: len_idata, len_rdata, len_cdata integer, intent(in) :: inc, nsurf, i2or3, isunit, len_vrel integer, intent(out) :: error_code 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



! uncomment to call existing implementation! 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.


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 data (integer, real and characters) required in the user subroutine. It should look like the following for EXT_SEPFOR application:

BCONUDS,bid,BCBODY,sname,SEPFOR,

,INT,…

,REAL,…

,CHAR,…

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_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.


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, in DynInt32 cidata );

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, in DynInt64 cidata );};

}; // sepfor}; // Contact}; // Uds}; // Obj}; // MDSolver}; // SCA

Note: The EXT_SEPFOR user subroutines are not available with segment-to-segment contact.


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 SCAInt64 inc, const SCAReal64 time, const SCAReal64 dtime, const SCAInt64 isunit, 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, & len_rdata, len_cdata, error_code) implicit none

integer, intent(in) :: len_idata, len_rdata, len_cdata integer, intent(in) :: ibody, inc, nnode, isunit integer, intent(out) :: error_code real(8), intent(in) :: time, dtime real(8), intent(out) :: fnorm, ftang



! uncomment to call existing implementation! 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.


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 data (integer, real and characters) required in the user subroutine. It should look like the following for EXT_SEPSTR application:

BCONUDS,bid,BCBODY,sname,SEPSTR,

,INT,…

,REAL,…

,CHAR,…

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_SEPSTR with the key word INT (REAL, CHAR).

Note: The EXT_SEPSTR user subroutines are not available with segment-to-segment contact.


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, in DynInt32 cidata );

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, in DynInt64 cidata );};

}; // sepstr}; // Contact}; // Uds}; // Obj}; // MDSolver}; // SCA

C++SCAResult Contact::usrSepstr_32(SCAReal64& snorm, SCAReal64& stang, const SCAInt32 ibody, const SCAInt32 nnode, const SCAInt32 inc, const SCAReal64 time, const SCAReal64 dtime, const SCAInt32 isunit, const sepstr::DynInt32& idata, const sepstr::DynReal64& rdata, const sepstr::DynInt32& cidata){ return SCASuccess;


68

} SCAResult Contact::usrSepstr_64(SCAReal64& snorm, SCAReal64& stang, const SCAInt64 ibody, const SCAInt64 nnode, const SCAInt64 inc, const SCAReal64 time, const SCAReal64 dtime, const SCAInt64 isunit, 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, & len_rdata, len_cdata, error_code) implicit none

integer, intent(in) :: len_idata, len_rdata, len_cdata integer, intent(in) :: ibody, inc, nnode, isunit integer, intent(out) :: error_code real(8), intent(in) :: time, dtime real(8), intent(out) :: snorm, stang



! uncomment to call existing implementation! 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.


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,…

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_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,


70

in SCAInt32 inc, out SCAReal64 stiff, out SCAReal64 fric, in SCAInt32 isunit, in DynInt32 idata, in DynReal64 rdata, in DynInt32 cidata);

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, in DynInt64 cidata);};

}; // 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,


& len_rdata, len_cdata, error_code) implicit none

integer, intent(in) :: len_idata, len_rdata, len_cdata integer, intent(in) :: nnode, i2or3, inc, isunit integer, intent(out) :: error_code 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


72

Required Output

STIFF is the average normal stiffness at the touched node (F/L3)

FRIC is the friction coefficient at the touched node

Chapter 2: User Defined Module Service UDMSRVUser Defined Services User’s Guide

2 User Defined Module Service UDMSRV

User Defined Module Service UDMSRV 2

Utility services 4

Memory management interface 5

Database access: 6

User Defined Services User’s GuideUser Defined Module Service UDMSRV

2

User Defined Module Service UDMSRV

IntroductionA 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,

3Chapter 2: User Defined Module Service UDMSRVUser 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 MYDMAPCOMPILE MYDMAP listSUBDMAP MYDMAP $TYPE DB,ZUZR11 $$TYPE PARM,NDDL,I,N,ZUZR1ZUZR1=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 8cendbegin bulkend data

User Defined Services User’s GuideUtility services

4

Utility servicesA set of utility interfaces are available to provide access to Nastran’s 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.

5Chapter 2: User Defined Module Service UDMSRVMemory management interface

Memory management interfaceThis 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;};

User Defined Services User’s GuideDatabase 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 integerTCID_Int64: // 64 bit integerTCID_Real32: // 32 bit realTCID_Real64: // 64 bit realTCID_String: // stringTCID_Bool: // Boolean

Code examples:

Please refer to examples that are supplied under <MSC_VERD>/nast/services directory.

Chapter 3: OpenFSIUser Defined Services User’s Guide

3 OpenFSI

Introduction 8

Running an OpenFSI MSC Nastran simulation 11

Creating an OpenFSI SCA service 22

Appendix 25

References 39


8

IntroductionThe OpenFSI functionality provides a mechanism to exchange fluid structure interaction data between

the MSC NastranTMsolver 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.

9Chapter 3: OpenFSIIntroduction

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.


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.

11Chapter 3: OpenFSIRunning an OpenFSI MSC Nastran simulation

Running an OpenFSI MSC Nastran simulation

OpenFSI input deckTo 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.

User Defined Services User’s GuideRunning an OpenFSI MSC Nastran simulation

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.OpenFSI’must 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:


Note: Unless indicated differently, the entries are defined in the bulk data section in the Nastran input file.


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:


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

WETELMEWETELMG

Case Control File Management

OpenFSISCA service

TLOAD1 WETLOAD FSICTRLDLOAD


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


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


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 INTEGER 6 None


Running MSC NastranTo 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.xmlsetenv 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.xmlexport 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 modelTable 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.xmlsetenv 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


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


Table 3-9 Nastran example input deck: example.dat.

User Defined Services User’s GuideCreating an OpenFSI SCA service

22

Creating an OpenFSI SCA service

Build tools and source filesTo 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/Toolssetenv 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.

23Chapter 3: OpenFSICreating an OpenFSI SCA service

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, it’s 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 implementationAs 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)

User Defined Services User’s GuideCreating an OpenFSI SCA service

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.

25Chapter 3: OpenFSIAppendix

Appendix

Interface Definition Language fileThe 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:

User Defined Services User’s GuideAppendix

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 shouldn’t 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


/// / \ | |

/// 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

///


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)


};

///

/// 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".


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)


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.


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.


/// (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) inout SCABool redoTimeStep );

///

/// 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


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 flowThe data flow for an OpenFSI MSC Nastran simulation is illustrated in Figure 3-4–Figure 3-5.


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.


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 debuggingReasons for a run time failure can be:


• 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


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

39Chapter 3: OpenFSIReferences

References1. 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).

User Defined Services User’s GuideReferences

40

Chapter 4: OpenFSI MSC Nastran & SimXpert Quick Start TutorialUser Defined Services User’s Guide

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

User Defined Services User’s GuideLaunch SimXpert and Import the Structural Model

42

Launch SimXpert and Import the Structural Model

43Chapter 4: OpenFSI MSC Nastran & SimXpert Quick Start TutorialDefine 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'

User Defined Services User’s GuideDefine the OpenFSI LBCs (Wettted Surfaces)

44

Define the OpenFSI LBCs (Wettted Surfaces)

45Chapter 4: OpenFSI MSC Nastran & SimXpert Quick Start TutorialDefine the OpenFSI LBCs (Wettted Surfaces)

User Defined Services User’s GuideDefine a Nonlinear Simulation

46

Define a Nonlinear Simulation

47Chapter 4: OpenFSI MSC Nastran & SimXpert Quick Start TutorialDefine a Nonlinear Simulation


48

49Chapter 4: OpenFSI MSC Nastran & SimXpert Quick Start TutorialDefine a Nonlinear Simulation


50

51Chapter 4: OpenFSI MSC Nastran & SimXpert Quick Start TutorialLaunch MSC Nastran OpenFSI-AcuSolve Simulation

Launch MSC Nastran OpenFSI-AcuSolve Simulation

User Defined Services User’s GuideLaunch MSC Nastran OpenFSI-MpCCI Simulation (for Fluent & StarCD)

52

Launch MSC Nastran OpenFSI-MpCCI Simulation (for Fluent & StarCD)

53Chapter 4: OpenFSI MSC Nastran & SimXpert Quick Start TutorialExamine the Results Using SimXpert

Examine the Results Using SimXpert

User Defined Services User’s GuideExamine the Results Using SimXpert

54

Chapter 5: OpenMDOUser Defined Services User’s Guide

5 OpenMDO

Introduction 2

Run MSC Nastran OpenMDO Optimization 6

Creating an OpenMDO SCA service 9

Appendix 13

Reference 16


2

IntroductionMSC 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 OpenMDOTM.

The OpenMDOTM 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. OpenMDOTM 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.

OpenMDOTM 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

3Chapter 5: OpenMDOIntroduction

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


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.

5Chapter 5: OpenMDOIntroduction

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).

User Defined Services User’s GuideRun MSC Nastran OpenMDO Optimization

6

Run MSC Nastran OpenMDO Optimization

OpenMDO Input DeckFor 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 NastranTo 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.xmlsetenv 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.xmlexport SCA_LIBRARY PATH=$SCAPATH/Apps/LX8664/lib/export SCA_RESOURCE DIR=$SCAPATH/Apps/res/

File management CONNECT SERVICE ALLDOTExternalOptimizer.OpenMD

O

Executive controlSOL200END

Case Control

DESOBJ = 10DESSUB=20SUBCASE 1 ANALYSIS = STATICS .

Bulk data

BEGIN BULK.DOPTPRM OPTCOD ALLDOT METHOD 1.

7Chapter 5: OpenMDORun MSC Nastran OpenMDO Optimization

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.

User Defined Services User’s GuideRun MSC Nastran OpenMDO Optimization

8

Table 5-1 Intermediate Complexity Wing Optimization Results

Initial ValueOptimum

DOT (MMFD)OptimumBIGDOT

OptimumIpopt

OptimumMSCADS (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

9Chapter 5: OpenMDOCreating an OpenMDO SCA service

Creating an OpenMDO SCA service

Build toolsTo 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/Toolssetenv 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 /Toolsexport 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 myOpenMDOTo build the implementation example myOpenMDO delivered with MSC Nastran, the following files are needed in the source directory:

myOpenMDO.cdlmyOpenMDO.cppmyOpenMDO.hmyOpenMDO.sdlSConscript

User Defined Services User’s GuideCreating an OpenMDO SCA service

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.

11Chapter 5: OpenMDOCreating an OpenMDO SCA service

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 ScratchThe 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.

User Defined Services User’s GuideCreating an OpenMDO SCA service

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.

13Chapter 5: OpenMDOAppendix

Appendix

Interface Definition Language fileThe 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.


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 OptimizationMethod, in SCAInt64 PrintControl, in SCAInt64 NumberOfDesignVariable, in SCAInt64 NumberOfConstraints, inout SCAReal64StaticArray DesignVariable, in SCAReal64StaticArray LowerBoundDesignVariable, in SCAReal64StaticArray UpperBoundDesignVariable, 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);

15Chapter 5: OpenMDOAppendix

/// /// Calculate Computer Memeory Requirements /// SCAResult EstimateMemory_32 ( in SCAInt32 NumberofDesignVariable, in SCAInt32 NumberofConstraint, in SCAInt32 OptimizationMethod, out SCAInt32 MinimumDimWk, out SCAInt32 DesiredDimWk, out SCAInt32 MaximumDimWk, out SCAInt32 DesiredDimIWk, out SCAInt32 ExtraSpace, inout SCAInt32 NumberOfCritialConstraint, in SCAReal64StaticArray LowerBoundDesignVariable, in SCAReal64StaticArray UpperBoundDesignVariable, inout SCAInt32 SizeofIOA, inout SCAInt32 SizeofROA, in SCAInt32 MaximumInteger, out SCAInt32 MemoryErrorFlag);

SCAResult EstimateMemory_64 ( in SCAInt64 NumberofDesignVariable, in SCAInt64 NumberofConstraint, in SCAInt64 OptimizationMethod, out SCAInt64 MinimumDimWk, out SCAInt64 DesiredDimWk, out SCAInt64 MaximumDimWk, out SCAInt64 DesiredDimIWk, out SCAInt64 ExtraSpace, inout SCAInt64 NumberOfCritialConstraint, in SCAReal64StaticArray LowerBoundDesignVariable, in SCAReal64StaticArray UpperBoundDesignVariable, inout SCAInt64 SizeofIOA, inout SCAInt64 SizeofROA, in SCAInt64 MaximumInteger, out SCAInt64 MemoryErrorFlag);

};

}; }; }; };

#endif

User Defined Services User’s GuideReference

16

Reference1. 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.

Ap. A: Quick Start Guide for User Defined ServicesUser Defined Services User’s Guide

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


18

IntroductionThis 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 you’re 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.

19Ap. A: Quick Start Guide for User Defined ServicesMSC SDK Delivery Contents

MSC SDK Delivery ContentsThe 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

http://software.intel.com/en-us/articles/older-version-product/

User Defined Services User’s GuideServices Implementation Examples

20

Services Implementation ExamplesImplementation 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

21Ap. A: Quick Start Guide for User Defined ServicesSupported Operating Systems and Compilers

Supported Operating Systems and CompilersUser 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-64SLIBmust 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.

PlatformWindows 32

and 64Linux 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

User Defined Services User’s GuideCompiling User Defined Services

22

Compiling User Defined ServicesYou 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\SConoptsUsing version 8.0 of Microsoft C++Using version 10.1.024 of Intel Fortran

Build Type = OPT on WINNTSource = C:\MSC.Software\MSC_SDK\MDr4Alpha2\ExamplesObject = C:\MSC.Software\MSC_SDK\MDr4Alpha2\Examples\WINNT_EXAMPLES_OPTApps Local = C:\MSC.Software\MSC_SDK\MDr4Alpha2\Examples\AppsApps System = C:\MSC.Software\MSC_SDK\MDr4Alpha2\SCAKernelTools System = C:\MSC.Software\MSC_SDK\MDr4Alpha2\Tools

34 Source directories processedscons: done reading SConscript files.scons: Building targets ...""(deleted for clarity)""scons: done building targets.

23Ap. A: Quick Start Guide for User Defined ServicesCompiling User Defined Services

See the FAQ questions below for advance usage of the scons command to utilize, for example, alternate compilers or non-standard compiler installation paths.

User Defined Services User’s GuideDefining the path to User Defined Service

24

Defining the path to User Defined ServiceA 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.

25Ap. A: Quick Start Guide for User Defined ServicesPointing to a User Defined Services from MSC Nastran

Pointing to a User Defined Services from MSC NastranEach 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.

User Defined Services User’s GuideRunning MSC Nastran with a User Defined Service

26

Running MSC Nastran with a User Defined ServiceOnce 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>.datNastran 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.

27Ap. A: Quick Start Guide for User Defined ServicesSDK User Services on other Operating Systems

SDK User Services on other Operating SystemsThere 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

User Defined Services User’s GuideErrors Messages and Diagnostics

28

Errors Messages and DiagnosticsTable 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

29Ap. A: Quick Start Guide for User Defined ServicesErrors Messages and Diagnostics

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\SConoptsWarning: 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.

User Defined Services User’s GuideErrors Messages and Diagnostics

30

Situation

User set the compiler settings to:export C=/usr/bin/gccexport CXX=usr/bin/gccexport CCOMPILER=gccThe error receive is the following:Warning: Intel C++ compiler version 10.1.017 not found - using 0 insteadWarning: Intel Fortran compiler version 10.1.017 not found - using 0 insteadError: 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:




31Ap. A: Quick Start Guide for User Defined ServicesFAQ

FAQ1. 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=322. 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:


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 compiler’s 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


User Defined Services User’s GuideFAQ

32

Ap. B: Compatibility MatrixUser Defined Services User’s Guide

B Compatibility Matrix

Product Compatibility Matrix

User Defined Services User’s GuideProduct Compatibility Matrix

34

Product Compatibility MatrixThis 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.32011

2010.1.32010

X

2010.1.2 2010 2010

2010 X 2010

MSC Nastran 2012 User Defined Services

Documents

environment

typedef scareal32

typedef scareal32

inout scabool

positive reaction

typedef scaint64

typedef scaint32

wettednode