Mechanical APDL as a Server User's Guide

ANSYS, Inc. Release 2020 R1

Southpointe January 2020
2600 ANSYS Drive
Canonsburg, PA 15317 ANSYS, Inc. and
ansysinfo@ansys.com ANSYS Europe,
Ltd. are UL
http://www.ansys.com registered ISO
(T) 724-746-3304 9001: 2015
(F) 724-514-9494 companies.
Copyright and Trademark Information

© 2020 ANSYS, Inc. Unauthorized use, distribution or duplication is prohibited.

ANSYS, ANSYS Workbench, AUTODYN, CFX, FLUENT 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 located 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. FLEXlm and FLEXnet are trademarks of Flexera Software LLC.

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. and ANSYS Europe, Ltd. are UL registered ISO 9001: 2015 companies.

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 Software Development Kit (SDK) ............................................................ 5
3.1. Requirements ................................................................................................................................... 5
3.2. Mechanical APDL as a Server CORBA Interfaces ................................................................................. 5
3.2.1. ICoMapdlUnit .......................................................................................................................... 5
3.2.2. Exceptions ............................................................................................................................... 6
3.2.3. Using the CORBA Interface ....................................................................................................... 7

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. iii
 Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
iv 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. 5).

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. 5) 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. 5) to build your
own custom client application in any programming language which supports the Common Object Request

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

Broker Architecture (CORBA). The SDK is composed of a set of Interface Definition Language (IDL) files
which, 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. 5).

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. 5) 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 2020 R1 - © ANSYS, 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
directory 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:\> ansys201 <options> -aas

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

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

Release 2020 R1 - © ANSYS, 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

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

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

Release 2020 R1 - © ANSYS, 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 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:

3.1. Requirements
3.2. Mechanical APDL as a Server CORBA Interfaces

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

3.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:
3.2.1. ICoMapdlUnit
3.2.2. Exceptions
3.2.3. Using the CORBA Interface

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

Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 5
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_pFileContent);
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
returned.

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.

3.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 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
6 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
}

3.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:\Program Files\ANSYS Inc\v201\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 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. 7
 Release 2020 R1 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
8 of ANSYS, Inc. and its subsidiaries and affiliates.