Installing and using Artelys Kalis

By reading this chapter, you will be able to:

  • install Artelys Kalis on your computer ;

  • verify that your license is correct ;

  • compile and run examples.

Installing Artelys Kalis

Artelys Kalis is supported on the platforms described in the table below.

PLATFORM

OPERATING SYSTEM

Windows 64-bit

Windows 10, Windows 8.1, Windows 8, Windows 7, Windows Server 2008, Vista

Linux 64-bit

Debian, RedHat (glibc2.5+) compatible (parallel features require OpenMP)

Mac OS 64-bit

OS X 10.11 (El Capitan)

For enquiries about using Artelys Kalis on unsupported platforms, please contact Artelys.

Instructions for installing the Artelys Kalis package on supported platforms are given below. After installing, view the INSTALL.txt and README.txt files, then test the installation by running one of the examples provided with the distribution.

The Artelys Kalis product contains example interfaces written in various programming languages under the directory examples. Each example consists of a main driver program coded in the given language that defines an optimization problem and invokes Artelys Kalis to solve it. Examples also contain a makefile illustrating how to link the Kalis library with the target language driver program.

Windows

The Artelys Kalis software package for Windows is delivered as a zipped file (ending in .zip), or as a self-extracting executable (ending in .exe). For the zipped file, double-click on it and extract all contents to a new folder. For the .exe file, double-click on it and follow the instructions. The self-extracting executable creates start menu shortcuts and an uninstall entry in Add/Remove Programs; otherwise, the two install methods are identical.

The default installation location for Artelys Kalis is (assuming your HOMEDRIVE is “C:"):

> C:\Program Files\Artelys

Unpacking will create a folder named Kalis 13.2.2. Contents of the full product distribution are the following:

  • INSTALL.txt: a file containing installation instructions.

  • licenseAgreement.txt: a file containing the Artelys Kalis license agreement.

  • readme.txt: a file with instructions on how to get started using Artelys Kalis.

  • releaseNotes.txt: a file containing release notes.

  • get_machine_ID: an executable that identifies the machine ID, required for obtaining a Artelys license file.

  • doc: a folder containing Artelys Kalis documentation, including this manual.

  • include: a folder containing the header files.

  • lib: a folder containing the Kalis library and object files.

  • bin: a folder containing the Kalis binaries.

  • examples: a folder containing examples of how to use the Artelys Kalis API in different programming languages (C++, Java, Python). The examples\C++ folder contains the most extensive set (see examples\C++\README.txt for details).

To activate Artelys Kalis for your computer you will need a valid Artelys license file. If you purchased a floating network license, then refer to the Artelys License Manager User’s Manual provided in the doc folder of your distribution.

For a stand-alone, single computer license, double-click on the get_machine_ID.bat batch file provided with the distribution. This will generate a machine ID (five pairs of hexadecimal digits). Alternatively, open a DOS-like command window (click Start / Run, and then type cmd). Change to the directory where you unzipped the distribution, and type get_machine_ID.exe, a program supplied with the distribution to generate the machine ID.

Email the machine ID to

\mbox{info-kalis@artelys.com}

if purchased through Artelys. (If Artelys Kalis was purchased through a distributor, then email the machine ID to your local distributor). Artelys (or your local distributor) will then send you a license file containing the encrypted license text string. The Artelys license manager supports a variety of ways to install licenses. The simplest procedure is to place each license file in the folder:

> C:\Program Files\Artelys\

(create the folder above if it does not exist). The license file name may be changed, but must begin with the characters artelys_lic. If this does not work, try creating a new environment variable called ARTELYS_LICENSE and set it to the folder holding your license file(s). See information on setting environment variables below and refer to the Artelys License Manager User’s Manual for more installation details.

Setting environment variables

In order to run Artelys Kalis binary or executable files from anywhere on your Windows computer, as well as load dynamic libraries (or dll’s) used by Artelys Kalis at runtime, it is necessary to make sure that the PATH system environment variable is set properly on your Windows machine. In particular, you must update the system PATH environment variable so that it indicates the location of the Artelys Kalis lib folder (containing the Artelys Kalis provided dll’s). This can be done as follows.

  • Windows 8

    • From the Windows Start screen, search for and open “Edit the system environment variables”.

    • Click the Advanced tab.

    • Click Environment Variables.

    • Under System variables, edit the Path variable to add the Artelys Kalis lib folder. Specify the whole path to this folder, and make sure to separate the paths by a semi-colon.

  • Windows Vista and Windows 7

    • At the Windows desktop, right-click “Computer”.

    • Select “Properties”.

    • Click on Advanced System Settings in the left pane.

    • In the System Properties window select the Advanced tab.

    • Click Environment Variables.

    • Under System variables, edit the Path variable to add the Artelys Kalis lib folder. Specify the whole path to this folder, and make sure to separate the paths by a semi-colon.

Note that you may need to restart your Windows machine after modifying the environment variables, for the changes to take effect. Simply logging out and relogging in is not enough. Moreover, if the PATH environment variable points to more than one folder that contains an executable or dll of the same name, the one that will be chosen is the one whose folder appears first in the PATH variable definition.

Unix (Linux, Mac OS X)

Artelys Kalis is supported on Linux (64-bit), Mac OS X (64-bit x86_64 on Mac OS X 10.8 or higher).

The Artelys Kalis software package for Unix is delivered as a gzipped tar file, or as a zip file on Mac OS X. Save this file in a fresh subdirectory on your system. To unpack a gzipped tar file, type the commands:

> gunzip kalis-13.0.1-platformname.tar.gz
> tar -xvf kalis-13.0.1-platformname.tar

Unpacking will create a directory named kalis-13.0.1. Contents of the full product distribution are the following:

  • INSTALL.txt: a file containing installation instructions.

  • licenseAgreement.txt: a file containing the Artelys Kalis license agreement.

  • readme.txt: a file with instructions on how to get started using Artelys Kalis.

  • releaseNotes.txt: a file containing release notes.

  • get_machine_ID: an executable that identifies the machine ID, required for obtaining a Artelys license file.

  • doc: a folder containing Artelys Kalis documentation, including this manual.

  • include: a folder containing the header files.

  • lib: a folder containing the Artelys Kalis library and object files.

  • examples: a folder containing examples of how to use the Artelys Kalis API in different programming languages (C++, Java, Python). The examples\C++ folder contains the most extensive set (see examples\C++\README.txt for details).

To activate Artelys Kalis for your computer you will need a valid Artelys license file. If you purchased a floating network license, then refer to the Artelys License Manager User’s Manual. For a stand-alone license, execute get_machine_ID, a program supplied with the distribution. This will generate a machine ID (five pairs of hexadecimal digits). Email the machine ID to

\mbox{info-kalis@artelys.com}

if purchased through Artelys. (If Artelys Kalis was purchased through a distributor, then email the machine ID to your local distributor). Artelys (or your local distributor) will then send a license file containing the encrypted license text string. The Artelys license manager supports a variety of ways to install licenses. The simplest procedure is to copy each license into your HOME directory. The license file name may be changed, but must begin with the characters artelys_lic (use lower-case letters). If this does not work, try creating a new environment variable called ARTELYS_LICENSE and set it to the folder holding your license file(s). See information on setting environment variables below and refer to the Artelys License Manager User’s Manual for more installation details.

Setting environment variables

In order to run Artelys Kalis binary or executable files from anywhere on your Unix computer, as well as load dynamic, shared libraries (i.e. “.so” or “.dylib” files) used by Artelys Kalis at runtime, it is necessary to make sure that several environment variables are set properly on your machine.

You must also update the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH on Mac OS X) environment variable so that it indicates the location of the Artelys Kalis lib directory (containing the Artelys Kalis provided “.so” or “.dylib” shared libraries).

Setting the PATH and LD_LIBRARY_PATH (DYLD_LIBRARY_PATH on Mac OS X) environment variables on Unix systems can be done as follows. In the instructions below, replace <file_absolute_library_path> with the full path to the directory containing the Artelys Kalis shared object library (e.g. the Knitro lib directory).

Linux

If you run a Unix bash shell, then type:

> export PATH= <file_absolute_path>:$PATH
> export LD_LIBRARY_PATH= <file_absolute_library_path>:$LD_LIBRARY_PATH

If you run a Unix csh or tcsh shell, then type:

> setenv PATH  <file_absolute_path>:$PATH
> setenv LD_LIBRARY_PATH  <file_absolute_library_path>:$LD_LIBRARY_PATH

Mac OS X

Determine the shell being used:

> echo $SHELL

If you run a Unix bash shell, then type:

> export PATH= <file_absolute_path>:$PATH
> export DYLD_LIBRARY_PATH=<file_absolute_library_path>:$DYLD_LIBRARY_PATH

If you run a Unix csh or tcsh shell, then type:

> setenv PATH  <file_absolute_path>:$PATH
> setenv DYLD_LIBRARY_PATH <file_absolute_library_path>:$DYLD_LIBRARY_PATH

Note that the value of the environment variable is only valid in the shell in which it was defined. Moreover, if a particular environment variable points to more than one directory that contains a binary or dynamic library of the same name, the one that will be chosen is the one whose directory appears first in the environment variable definition.

If you are setting the ARTELYS_LICENSE environment variable to activate your license, then follow the instructions above to create a new environment variable called ARTELYS_LICENSE and give it the value of the directory containing your Ziena license file (specify the whole path to this directory). For more installation options and general troubleshooting, read the Artelys License Manager User’s Manual.