ANSYS Mechanical APDL as a Server User's

Guide

ANSYS, Inc. Release 17.0

Southpointe January 2016
2600 ANSYS Drive
Canonsburg, PA 15317 ANSYS, Inc. is
ansysinfo@ansys.com certified to ISO
9001:2008.
http://www.ansys.com
(T) 724-746-3304
(F) 724-514-9494
Copyright and Trademark Information

© 2015 SAS IP, Inc. All rights reserved. Unauthorized use, distribution or duplication is prohibited.

ANSYS, ANSYS Workbench, Ansoft, AUTODYN, EKM, Engineering Knowledge Manager, CFX, FLUENT, HFSS, AIM
and any and all ANSYS, Inc. brand, product, service and feature names, logos and slogans are registered trademarks
or trademarks of ANSYS, Inc. or its subsidiaries in the United States or other countries. ICEM CFD is a trademark
used by ANSYS, Inc. under license. CFX is a trademark of Sony Corporation in Japan. All other brand, product,
service and feature names or trademarks are the property of their respective owners.

Disclaimer Notice

THIS ANSYS SOFTWARE PRODUCT AND PROGRAM DOCUMENTATION INCLUDE TRADE SECRETS AND ARE CONFID-
ENTIAL AND PROPRIETARY PRODUCTS OF ANSYS, INC., ITS SUBSIDIARIES, OR LICENSORS. The software products
and documentation are furnished by ANSYS, Inc., its subsidiaries, or affiliates under a software license agreement
that contains provisions concerning non-disclosure, copying, length and nature of use, compliance with exporting
laws, warranties, disclaimers, limitations of liability, and remedies, and other provisions. The software products
and documentation may be used, disclosed, transferred, or copied only in accordance with the terms and conditions
of that software license agreement.

ANSYS, Inc. is certified to ISO 9001:2008.

U.S. Government Rights

For U.S. Government users, except as specifically granted by the ANSYS, Inc. software license agreement, the use,
duplication, or disclosure by the United States Government is subject to restrictions stated in the ANSYS, Inc.
software license agreement and FAR 12.212 (for non-DOD licenses).

Third-Party Software

See the legal information in the product help files for the complete Legal Notice for ANSYS proprietary software
and third-party software. If you are unable to access the Legal Notice, Contact ANSYS, Inc.

Published in the U.S.A.

Table of Contents
1. Introduction ............................................................................................................................................ 1
1.1. Overview .......................................................................................................................................... 1
1.2. Limitations ....................................................................................................................................... 2
1.3. Installation Requirements ................................................................................................................. 2
1.3.1. Server Machine ........................................................................................................................ 2
1.3.2. Client Machine ......................................................................................................................... 2
2. Mechanical APDL as a Server Session Management .............................................................................. 3
2.1. Mechanical APDL as a Server Sessions ............................................................................................... 3
2.1.1. Starting Mechanical APDL in Server Mode ................................................................................ 3
2.1.1.1. Starting Server Mode from the Mechanical APDL Product Launcher ................................. 3
2.1.1.2. Starting Server Mode from the Command Line ................................................................. 3
2.1.2. Mechanical APDL as a Server Keyfile ......................................................................................... 4
2.2. Connecting to Mechanical APDL in Server Mode ............................................................................... 4
3. Mechanical APDL as a Server Matlab Toolbox ........................................................................................ 5
3.1. Installing the Matlab Toolbox ............................................................................................................ 5
3.2. Using the Matlab Toolbox ................................................................................................................. 5
3.3. Uninstalling or Upgrading the Matlab Toolbox ................................................................................... 6
4. Mechanical APDL as a Server Software Development Kit (SDK) ............................................................ 7
4.1. Requirements ................................................................................................................................... 7
4.2. Mechanical APDL as a Server CORBA Interfaces ................................................................................. 7
4.2.1. ICoMapdlUnit .......................................................................................................................... 7
4.2.2. Exceptions ............................................................................................................................... 8
4.2.3. Using the CORBA Interface ....................................................................................................... 9

Release 17.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. v
 Release 17.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
vi of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 1: Introduction
ANSYS Mechanical APDL as a Server is a set of tools and functionality that allows local or remote client
applications to access and interact with a running session of Mechanical APDL. A client application can
perform case setup, initialization, iteration, and intermediate and final result reporting using the
Mechanical APDL as a Server interface. This function is different from batch mode in that commands
can be issued to the running session at any time in addition to a predefined file. This allows for solution
steering and other manipulation without exiting from the running simulation. Client applications can
be built using the Mechanical APDL as a Server Software Development Kit (SDK) (p. 7).

The follow are some examples of how Mechanical APDL as a Server functionality could be used to ma-
nipulate Mechanical APDL remotely and provide information of interest from a running simulation:

• A company with offices in several locations designs a remote console program for issuing commands to
Mechanical APDL as a Server. Users at this company run all their simulations with the Mechanical APDL as
a Server functionality turned on. When a user requires assistance from a subject-matter expert in a different
office, the expert can run the remote console and issue commands to examine results, change settings, and
assist the user in obtaining a solution.

• A user would like to have remote monitoring capability for long-running simulations. The user writes a
program which can query the running simulation using the Mechanical APDL as a Server functionality. This
program delivers information about the solve process to a website, which the user can monitor. The site
can also pass commands to the simulation process, or remotely terminate the simulation.

1.1. Overview
The following elements, provided with ANSYS Mechanical APDL, make up the Mechanical APDL as a
Server capability:

• The ANSYS Mechanical APDL application with built-in Internet Inter-ORB Protocol (IIOP) interface.

• The Mechanical APDL as a Server Software Development Kit (SDK) (p. 7) which enables you to build custom
client applications.

The Mechanical APDL as a Server interface exists alongside the graphical user interface and the batch
mode interface. It is made available by starting Mechanical APDL in server mode, as described in Starting
Mechanical APDL in Server Mode (p. 3). A client connected to the Mechanical APDL as a Server interface
can then be used to issue commands remotely to the running Mechanical APDL session.

The information necessary to connect to the Mechanical APDL as a Server session is stored as an Inter-
operable Object Reference (IOR) string in a text file on the server machine when the session is started.
This IOR string is unique to the session and can be used by a client application to read all necessary
information to connect to the Mechanical APDL as a Server session (for example, hostname, port number,
protocol). For further details, see Mechanical APDL as a Server Session Management (p. 3).

You can use the Mechanical APDL as a Server Software Development Kit (SDK) (p. 7) to build your
own custom client application in any programming language which supports the Common Object Request
Broker Architecture (CORBA). The SDK comprises a set of Interface Definition Language (IDL) files which,

Release 17.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 1
Introduction

when compiled with a 3rd party CORBA compiler, provide a set of libraries which you can include in
your application to enable communication with Mechanical APDL as a Server. For further details, see
Mechanical APDL as a Server Software Development Kit (SDK) (p. 7).

1.2. Limitations
Mechanical APDL as a Server has the following limitations:

• Commands issued to the Mechanical APDL as a Server instance are not executed until Mechanical APDL is
idle or has reached a stable point. For example, Mechanical APDL is not stable while solving during an
equilibrium iteration, but at the beginning of the equilibrium iteration there is a stable point. This means
that there may be a lag between when the client program enters a command and when a response is issued
from Mechanical APDL.

1.3. Installation Requirements

The following installation topics are available:
1.3.1. Server Machine
1.3.2. Client Machine

1.3.1. Server Machine

A standard ANSYS Mechanical APDL installation is all that is required on the server machine to start a
Mechanical APDL as a Server session that can listen to commands from clients. For more information,
see Mechanical APDL as a Server Session Management (p. 3).

1.3.2. Client Machine

You can connect from a client machine using applications built with the Mechanical APDL as a Server
Software Development Kit (SDK) (p. 7) in any CORBA-compliant programming language. These client
applications will have varying installation procedures and system requirements depending on how they
are built and the amount of system resources required to execute them.

Release 17.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
2 of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 2: Mechanical APDL as a Server Session Management
The following topics are available for starting and managing Mechanical APDL as a Server sessions to
be accessed by remote client applications.
2.1. Mechanical APDL as a Server Sessions
2.2. Connecting to Mechanical APDL in Server Mode

2.1. Mechanical APDL as a Server Sessions

A Mechanical APDL as a Server session is similar to a conventional Mechanical APDL session, with the
addition of an Internet Inter-ORB Protocol (IIOP) interface that accepts connections from suitable client
applications. This function is different from batch mode in that commands can be issued to the running
session at any time in addition to a predefined file. This allows for solution steering and other manipu-
lation without exiting from the running simulation.

2.1.1. Starting Mechanical APDL in Server Mode

You can start Mechanical APDL in Server Mode in two ways:
2.1.1.1. Starting Server Mode from the Mechanical APDL Product Launcher
2.1.1.2. Starting Server Mode from the Command Line

In either case, the Mechanical APDL as a Server session generates a keyfile in the session working dir-
ectory with the information necessary for a client to connect to the session. For more information, see
Mechanical APDL as a Server Keyfile (p. 4) and Connecting to Mechanical APDL in Server Mode (p. 4).

2.1.1.1. Starting Server Mode from the Mechanical APDL Product Launcher
From the Customization/Preferences tab, add -aas to the Additional Parameters.

2.1.1.2. Starting Server Mode from the Command Line

Use the following commands to start Mechanical APDL in server mode:

• On Windows platforms:
C:\> ansys170 <options> -aas

• On Linux platforms:
> ansys170 <options> -aas

These commands assume that the Mechanical APDL executable is refered to in your PATH environment
variable.

For more information on command line options in Mechanical APDL, see Starting a Mechanical APDL
Session from the Command Level in the Operations Guide.

Release 17.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 3
Mechanical APDL as a Server Session Management

2.1.2. Mechanical APDL as a Server Keyfile

As described in Starting Mechanical APDL in Server Mode (p. 3), when you start a Mechanical APDL
as a Server session, a keyfile is created in the session working directory that contains the information
required for a client application to connect to the session. The keyfile is a text file containing in Inter-
operable Object Reference (IOR) string that contains information about the host, port number, and
protocol for connecting to the Mechanical APDL as a Server session.

You can use the -iorFile keyfilename command line argument to specify the name of the keyfile.
If you do not provide this argument, the file is named aas_MapdlID.txt by default.

If a keyfile already exists that refers to a running Mechanical APDL as a Server session, the new Mech-
anical APDL as a Server session will fail to start. This behavior prevents inadvertently overwriting a
keyfile.

2.2. Connecting to Mechanical APDL in Server Mode

Once a Mechanical APDL as a Server session is running, it is available for connections from local or remote
client applications that have network access to the server machine.

In order to connect to the Mechanical APDL as a Server session, you need access to the IOR string
contained in the keyfile generated by the session (Mechanical APDL as a Server Keyfile (p. 4)). Because
the keyfile is a text file, any means of copying the file or its contents to a location accessible to the client
machine can be used.

You can connect to Mechanical APDL as a Server using clients built with the Mechanical APDL as a
Server CORBA interfaces that are supplied as part of the Mechanical APDL as a Server Software Devel-
opment Kit (SDK) (p. 7).

Release 17.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
4 of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 3: Mechanical APDL as a Server Matlab Toolbox
The Mechanical APDL as a Server Matlab Toolbox is provided to allow you to control Mechanical APDL
from within a Matlab session. This toolbox connects Mechanical APDL as a Server with Matlab to allow
data to pass between the two applications.
3.1. Installing the Matlab Toolbox
3.2. Using the Matlab Toolbox
3.3. Uninstalling or Upgrading the Matlab Toolbox

3.1. Installing the Matlab Toolbox

Use the following steps to install the Mechanical APDL as a Server Matlab toolbox:

1. Verify that you have a supported version of Matlab. The Mechanical APDL as a Server Toolbox is compatible
with Matlab R2014b and R2015a. The toolbox is compatible with 32-bit and 62-bit Windows, Mac OS X,
and Linux operating systems.

2. Obtain the AnsysAAS.mltbx toolbox file from the ANSYS Customer Portal.

3. Start Matlab and open the local folder where the AnsysAAS.mltbx file is located.

4. Double-click the AnsysAAS.mltbx file to launch the toolbox installer.

5. Click the Install button in the dialog window to perform the installation. You will see a temporary notific-
ation on the Add-Ons menu that the toolbox has been successfully installed.

6. Verify the installation by clicking the Add-Ons > Manage Custom Toolboxes button.

3.2. Using the Matlab Toolbox

Use the following steps to configure and connect the Matlab toolbox to a running Mechanical APDL as
a Server session:

1. Execute the command load_ansys_aas to load the dynamic libraries. This should be executed once
per Matlab session, before any other steps are taken. If the dynamic libraries are already loaded (the com-
mand has been executed already for this Matlab session), a warning will be generated.

2. Create a Matlab Object Request Broker (ORB) using the command orb=initialize_orb.

If you are currently using the ORB distributed with Matlab, you can issue the following 3 commands
to create the ORB:

args = javaArray('java.lang.String',1);
props=[];
orb=org.omg.CORBA.ORB.init(args,props);

3. Start Mechanical APDL in Server Mode (p. 3) on the host machine. The aaS_MapdlId.txt file is created.

Release 17.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 5
Mechanical APDL as a Server Matlab Toolbox

4. Copy the aaS_MapdlId.txt file from the host machine to the Matlab machine.

5. Use the ORB and the aaS_MapdlId.txt file to create a Mechanical APDL object in Matlab that connects to
the session on the host machine by issuing the command mapdl=actmapdlserver(orb,'aaS_Map-
dlId.txt').

6. Use the mapdl object to interact with the running Mechanical APDL as a Server session on the host machine.
The following is an example command to create a parameter: mapdl.executeCommandTo-
String('aas_parameter=12.345').

For a complete listing of Mechanical APDL commands, refer to the Command Reference. For more
information on CORBA commands available to the Matlab toolbox, see Mechanical APDL as a Server
CORBA Interfaces (p. 7).

3.3. Uninstalling or Upgrading the Matlab Toolbox

Use the following steps to uninstall or upgrade the Matlab Toolbox:

1. Start Matlab and click the Add-Ons > Manage Custom Toolboxes button.

2. In the dialog window, click the Uninstall link in the AnsysAAS item.

3. Restart Matlab by closing and re-opening the application.

4. If you are upgrading the toolbox, follow the instructions found in Installing the Matlab Toolbox (p. 5) to
install the new toolbox.

Release 17.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
6 of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 4: Mechanical APDL as a Server Software Development Kit
(SDK)
The Mechanical APDL as a Server Software Development Kit (SDK) is included with the standard install-
ation of ANSYS Mechanical APDL and allows you to create your own client applications to connect to
and communicate with Mechanical APDL as a Server sessions. Using the SDK, you can extend or create
a client application to provide control or monitoring of Mechanical APDL simulations.

The following topics are available:

4.1. Requirements
4.2. Mechanical APDL as a Server CORBA Interfaces

4.1. Requirements
In order to use the Mechanical APDL as a Server SDK to create client applications that connect to
Mechanical APDL as a Server sessions, you will need a development environment with native or 3rd
party support for the Common Object Request Broker Architecture (CORBA) and a suitable CORBA IDL
compiler. The following widely-used programming languages have native or 3rd party CORBA support:

• C and C++

• COBOL

• Ruby

• Python

• Java

4.2. Mechanical APDL as a Server CORBA Interfaces

The central element of the Mechanical APDL as a Server SDK is a CORBA interface you can use in
building a client application. This interface is included in the standard installation of Mechanical APDL.

The following topics describe the CORBA interface and its use:
4.2.1. ICoMapdlUnit
4.2.2. Exceptions
4.2.3. Using the CORBA Interface

4.2.1. ICoMapdlUnit
The ICoMapdlUnit interface provides a set of functions that perform typical commands in ANSYS
Mechanical for solving a simulation.

Release 17.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 7
Mechanical APDL as a Server Software Development Kit (SDK)

Interface ICoMapdlUnit

string getComponentName();
Returns the name of the connected component.

void setComponentName(in string name);

Sets the name of the component to name.

string getComponentDescription();
Returns the description of the connected component.

void setComponentDescription(in string desc);

Sets the description of the connected component to desc.

void uploadFileFromBuffer(in string p_szFileName, in CoOctetBuffer p_pFile-

Content);
Writes a file named p_szFileName in the remote Mechanical APDL session working directory with
the contents of p_pFileContent. If p_szFileName exists, it is overwritten.

CoOctetBuffer downloadFileFromBuffer(in string p_szFileName);

Returns the contents of the file name p_szFileName in the remote Mechanical APDL session working
directory.

void executeCommand(in string p_stringCommand);

Issues a command to the connected Mechanical APDL session. Output from the command is not re-
turned.

string executeCommandToString (in string p_stringCommand);

Issues a command to the connected Mechanical APDL session and returns the output as a string.

void terminate();
Terminates the connected Mechanical APDL as a Server session.

4.2.2. Exceptions
The following exceptions can be generated by a Mechanical APDL as a Server session, and should be
appropriately handled by client applications:

exception EAnsysUnknown {
long code; Code for the exception
string description; Short description of the exception
string scope; Area from where the exception has been thrown
string interfaceName; Interface generating the exception (currently only
ICoMapdlUnit)
string operation; Method called
string moreInfo; Additional information about the exception
}

exception EAnsysInvalidArgument {
long code; Code for the exception

Release 17.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
8 of ANSYS, Inc. and its subsidiaries and affiliates.
 Mechanical APDL as a Server CORBA Interfaces

string description; Short description of the exception

string scope; Area from where the exception has been thrown
string interfaceName; Interface generating the exception (currently only
ICoMapdlUnit)
string operation; Method called
string moreInfo; Additional information about the exception
short position; Position of the invalid argument
}

4.2.3. Using the CORBA Interface

In order to use the CORBA interface for your client application, you must build the interface modules
for your development environment by compiling the supplied Interface Definition Language (IDL) file
using a suitable IDL compiler.

In a standard installation, the Mechanical APDL as a Server IDL file is located in the directory C:\Pro-
gram Files\ANSYS Inc\v170\ansys\customize\user.

Refer to the documentation for your CORBA implementation and development environment for details
on how to compile the IDL file and including the resulting modules in your application.

Release 17.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 9
 Release 17.0 - © SAS IP, Inc. All rights reserved. - Contains proprietary and confidential information
10 of ANSYS, Inc. and its subsidiaries and affiliates.