Getting Started with STK Engine on Linux

This help system, which focuses only on STK Engine on Linux, assumes that you are familiar with the Ansys Systems Tool Kit^® (STK^®) application. To learn more about the STK application, visit the STK Desktop help.

The following sections provide information that will help get you started with STK Engine:

• System Requirements. Includes information on hardware and software requirements.
• Installation. Provides step-by-step instructions for installing the STK Engine Development Kit.
• Accessing the STK Engine Help System. Tells how to access the STK Engine help system.
• Setting Up the Environment. Tells how to setup the Linux environment for STK Engine, about the new user install, online data, and how to set proxy settings.
• Obtaining and Registering Licenses. Tells how to obtain and register product licenses.
• Testing the Installation. Provides instructions for verifying that the development environment was set up correctly.
• Verify Development Environments. Provides instructions for verifying that the Java and Python development environments are working properly.
• STK Functionality Not Supported on Linux. Provides a list of STK application functionality that is not currently supported on Linux.

These sections differentiate three use cases:

• Desktop application

  Your application uses the STK Engine widgets to interactively display a map and/or globe.

• Compute node with no graphics

  Your application runs on a server as a compute engine and does not use STK Engine to generate graphics artifacts. This requires activating the STK Engine NoGraphics mode. In no graphics mode, there are no dependencies on OpenGL or X11, and a video card is not required.

• Compute node with graphics

  Your application runs on a server as a compute engine and uses STK Engine to generate graphics artifacts, for instance VDFs, videos or images.

  The default font for graphics is helvetica. If your system does not have helvetica installed, the fonts may not display properly. To check if helvetica is installed, run the command:

  xlsfonts | grep -i helvetica

System requirements

Supported operating systems

The following table lists the specific distributions and versions tested, and for which installation directions are provided. Other Linux distributions are likely to work as well, assuming the required dependencies are installed and available.

Operating System	Latest update or service pack tested
Red Hat Enterprise Linux / Rocky	8.10
Ubuntu Desktop	22.04

Hardware and software requirements

The following table lists the hardware and software requirements.

Hardware/Software	Requirements
Development disk space	1.76 GB
Deployment disk space	1.25 GB minimum, possibly more depending on specific application requirements
OpenGL / Video Card	Desktop Application High-end, OpenGL-compatible card (512+ MB RAM) that supports OpenGL 2.0+. It is possible for Nouveau drivers, which are the default NVidia drivers on Ubuntu Linux, to cause STK to terminate when using STK in graphics mode. If this problem occurs, it is recommended that you install the proprietary NVidia drivers. Compute Node, with graphics OpenGL 4.5+ using mesa software driver (possibly provided by xvfb) Compute Node, no graphics No video card/GPU requirement, OpenGL not used
Java	Oracle Java 8 update 25 minimum (Required if developing a Java application)
Python	Python version 3.8 or greater (Required if developing a Python application) and the Python API
libstdc++.so	6.0.19 minimum
Fortran Runtime	The 64-bit version of libgfortran.so.5 is required only for Fortran-dependent features, such as Astrogator SNOPT/IPOPT Search Profile plugins, VOACAP, and the IRI2016 Ionosphere library. You can use the following commands to find the package that provides a library: RHEL/Rocky: yum whatprovides libgfortran.so.5. On the Ubuntu website, you can search the 'Ubuntu Packages Search' page at https://packages.ubuntu.com/ for the contents of the packages by providing the file name (e.g., libgfortran.so.5) as a keyword.
MODTRAN	The 6.0.2.3 version of MODTRAN is required only if you wish to use Spectral Science Inc.'s MODTRAN atmospheric model for optical, infared, and ultra-violet frequencies.

If you are developing an interactive desktop application that integrates the STK Engine 2D and 3D controls, the following recommendations apply to the video card:

• The STK application uses OpenGL for all 2D and 3D rendering. For best rendering performance, high-end OpenGL-compatible cards (512+ MB RAM) that support OpenGL 4.5+ are recommended.

• For optimal performance, it is critical that the drivers for the video card be kept up to date. A good practice to follow is to update video drivers whenever the version of STK is updated.

• Starting with STK application version 13.0, OpenGL 4.5+ is a hard requirement. Systems without OpenGL 4.5 or greater will not be able to run the STK application.

• Video cards based on chipsets from NVidia have shown excellent performance and compatibility with the STK application.

Supplementary data requirements

Supplementary Data	Requirement
AGI Planetary Data	542 MB
World Terrain	252 MB
MODTRAN data	357 MB

Java Development Environment

While many Java Integrated Development Environments (IDE) (such as Eclipse, NetBeans, JBuilder, etc.) versions can be used with the STK Java API, our samples have been developed/tested specifically with the following IDEs and tools.

Tool	Version
Eclipse	4.3
Ant	1.9

Installation

There are two disk media or downloads required for this: 

• STK Engine for Unix 13.0
• STK Engine Supplementary Data for Unix 13.0

The downloads can be found here (https://support.agi.com/downloads/#unix). The following files are included:

File	Description
stk_binaries_v13.0.tgz	The 64-bit STK shared libraries.
stk_data_v13.0.tgz	The core STK data.
stk_jars_v13.0.tgz	The STK Java API jar files (including Javadoc). (Required if developing a Java Application)
stk_codesamples_v13.0.tgz	The STK Java API code samples (Contains all the STK Java API and STK Python API examples, including the examples for STK Desktop/Windows development).
stk_documentation_v13.0.tgz	The documentation.
AnsysLicensingClient_UI.tgz	Desktop Utility to connect to the license server.
AnsysLicenseManager.tgz	License manager install files.
stk_planetary_data_v13.0.tgz	The Supplementary STK data for interplanetary support.
stk_world_terrain_v13.0.tgz	The Supplementary world terrain data.
stk_modtran_data_v13.0.tgz	The Supplementary MODTRAN data.
stk_eoir_dataset_v13.0.tgz	The Supplementary EOIR data.

Java prerequisites

A few dependencies are required in order to develop and run STK Engine on Linux examples and custom applications:

• 64-bit Java JDK and JRE need to be available in order to respectively compile and run STK Engine applications. We recommend the official Java distribution from Oracle. Alternatively you can try openjdk.
• Eclipse and/or ant are needed to run the code samples (as eclipse project files and ant scripts are provided to compile and execute the examples).

The following instructions assume that you are already familiar with installing java/eclipse/ant on your platform. Therefore, we expect those tools to already be up and running on your machine.

Python prerequisites

There is one dependency required in order to develop and run STK Engine on Linux examples and custom applications:

• Python 3.8 or greater

Linux package dependencies

The following packages may need to be installed (if not already installed).

Package	Commands
64-bit Java JDK/JRE	Preferably Oracle Java. See https://java.com/en/download/faq/develop.xml. Alternatively the system default openjdk install. (Required if developing a Java Application)
libnsl	On certain operating systems, it is possible that libnsl.so is not installed. To resolve this dependency, run the following command: sudo yum install libnsl On some systems only libnsl.so.2 is available, in some cases the following workaround will fix the issue: ln -s /usr/lib64/libnsl.so.2.0.0 /usr/lib64/libnsl.so.1
Python	Version 3.8 or higher. (Required if developing a Python Application)

Additionally, for the Desktop and Compute mode with Graphics use cases:

Package	Commands
OpenGL Driver	Preferably native driver for your video card. Additionally, the mesa library: mesa-libGLU.x86_64

Unpacking STK Engine

For each download or media disk to install the core STK Engine files (needed both for development and deployment), issue the following commands:

To install the licensing client UI, issue the following command:

If developing a Java application, issue the following command to install STK Java API:

If developing a Python application, issue the following command to install the STK Python API:

To install the documentation and the code samples (only needed for development), issue the following commands:

If your application requires inter-planetary capabilities, issue the following command to install the additional interplanetary data files:

This will create a top level directory structure (with additional sub-directories not explicitly listed here) similar to:

The top level stk13.0 directory is referred to as the <STK Install folder> in the following sections.

Accessing the STK Engine on Linux Help System

The help system is provided as static html files. Using your preferred web browser open the <STK Install folder>/Help/index.htm file. For instance with firefox:

firefox <STK Install folder>/Help/index.htm

Setting up the Environment

Three environment variables need to be set. Note that these variables can be set from the shell or at initialization in your custom application if it is more convenient for your specific workflow.

The path to the bin directory needs to be added to your LD_LIBRARY_PATH environment variable:

bash: export LD_LIBRARY_PATH=<STK Install folder>/bin:$LD_LIBRARY_PATH

csh: setenv LD_LIBRARY_PATH=<STK Install folder>/bin:$LD_LIBRARY_PATH

Two environment variables need to be set up to indicate where STK Engine reads its data from and where it stores the user specific configuration:

bash:

export STK_INSTALL_DIR=<STK Install folder>
export STK_CONFIG_DIR=<location for user specific configuration data>

csh:

setenv STK_INSTALL_DIR=<STK Install folder>
setenv STK_CONFIG_DIR=<location for user specific configuration data>

For the user specific configuration data, STK Engine will automatically create a subdirectory and use it to store the configuration. This directory will be named <$STK_CONFIG_DIR/STK13>. Under this directory you will find the user specific defaults, preferences, and configuration. By default, STK Engine will create a configuration allowing online access to the internet. If you are on a private network with no internet access, these defaults can be tweaked using the new user install.

Do not copy the $STK_CONFIG_DIR/STK13 directory from one location on the disk to another location, or from one user to another user. The files under this directory contain absolute paths that would break if the files are moved. Instead of copying the files, re-initialize the configuration directory at the new location using one of the methods described next.

New-user install, online data, and proxy

By default STK Engine initializes transparently the user configuration the first time an application exercising engine is run for a specific user. The default configuration configures STK Engine to allow access to the internet for downloading additional data, such as Bing imagery, databases, TLE files, and other data from the AGI Web site during an STK session.

This default is not appropriate if your machine does not have internet access. On a network with no internet access, STK Engine tries to connect to the AGI data sources, possibly incurring delays at startup. To prevent that situation, disable online access. This can be done using the <STK Install folder>/bin/stkxnewuser command line utility, or from your custom application code.

To disable online access using the command line utility:

<STK Install folder>/bin/stkxnewuser --allowOnline=no

The stkxnewuser utility can also be used to reinitialize the user configuration to the default settings. It uses the $STK_CONFIG_DIR to determine where to store the user information.

Disabling online access can also be achieved programmatically at startup in your custom application using the following interfaces and methods:

IAgSTKXApplication app = …;
app.executeCommand(“SetOnlineOperations / Off”);

It is also possible that your network provides access to the internet but behind a proxy that requires authentication. In that case your custom application needs to configure the proxy at startup using the following snippet:

IAgSTKXApplication app = …;
app.setOnlineOptions(<useProxy?>, <server>, <port>, <user>, <password>, <save password?>);

Out of the box the code samples included in this version do not configure a proxy. So if you are in this situation and want to enable online access when running the code samples, you will need to add this snippet code to the example initialization.

MODTRAN Environment setup

Two environment variables need to be set. You can set up these variables from the shell or at initialization in your custom application, if it is more convenient for your specific workflow.

The path to the bin directory needs to be added to your LD_LIBRARY_PATH environment variable:

bash: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<MODTRAN Install folder>/bin/linux

csh: setenv LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<MODTRAN Install folder>/bin/linux

The path to the data directory needs to be set up:

bash: export MODTRAN_DATA=<MODTRAN Install folder>/DATA

csh: setenv MODTRAN_DATA=<MODTRAN Install folder>/DATA

Obtaining and Registering AGI Licenses

To run STK Engine, a license server is required. AGI uses the Ansys License Manager, powered by FlexNet Manager, for its licensed products. The Ansys License Manager is required to serve your license locally or from a network. All STK licenses come with an stk_engine_runtime license for STK Engine so that you can develop, deploy, and run STK/X engine-based applications.

For more information on licensing, refer to the following STK licensing topics:

• STK Licensing Overview

• Request a Purchased License

• Network License Overview

Testing the Installation

Use the following procedure to verify that the development environment was set up correctly.

Check Native Library Setup

The first step to verify that your installation is functional is to verify that the native libraries required by STK Engine are available on your system.

1. To verify that the dependencies required for computations are available, issue the following command:

ldd -r <STK Install folder>/bin/libagstkxengine.so | grep "not found"

2. In the case of the Desktop application and/or Compute node with graphics use cases, also issue the following command to verify that the native libraries required for graphics are available:

ldd -r <STK Install folder>/bin/libagstkobjectgfx.so | grep "not found"

3. To verify that the libgfortran dependency required for the Astrogator SNOPT/IPOPT Search Profile plugins, VOACAP, and the IRI2016 Ionosphere library is available, issue the following command:

ldd -r <STK Install folder>/bin/libagasiri2016fort.so | grep "not found"

The above commands should not find any match, and just return without printing any output. If missing dependencies are reported, the missing libraries need to be installed using the package management tools for your linux distribution (i.e., yum or apt-get).

4. To verify that the libgfortran.so dependency required for VOACAP is available, issue the following command:

ldd -r <STK Install folder>/bin/libagvoacapfortraninterface.so | grep "not found"

5. Once the above tests successfully passes, run connectconsole, a small utility that can be used to exercise STK Engine through Connect. Start the utility using (note that the option is specified using two dashes (--).

<STK Install folder>/bin/connectconsole --noGraphics --interactive

Connectconsole waits for a Connect command to be sent.

If you do not have an Integration license, connectconsole will exit and return this message: STK Engine Runtime license not found: exiting.

6. You can exit using CTRL-C. This indicates that all the required dependencies and shared libraries are available.
7. At this point, if your application requires using the STK Engine 2D & 3D controls and graphics support, you might also want to check that OpenGL is working. If everything is set-up correctly, the command below will open a new scenario with a 2D and 3D view.

<STK Install folder>/bin/connectconsole --new --interactive

Now that you have verified that all the shared libraries are available and functional, the next step is to verify that the your development environment works properly.

Verify Development Environments

Verifying Setup of STK Java API

If you unpacked stk_jars_v13.0.tgz file from the Unpacking STK Engine section, you can verify the STK Java API installation by following the steps in STK Java API - Verifying Setup of Java Code Samples.

Verifying Setup of STK Python API

If you installed the Python .whl file from the Unpacking STK Engine section, you can verify the STK Python API installation by following the steps in STK Python API - Verify the installation.