Installation Guide

This chapter introduces how to install Cardinal Optimizer on all supported operating systems, and how to obtain and setup license correctly. We recommend all users ready this chapter carefully before using Cardinal Optimizer.

Registration

Before using Cardinal Optimizer, users need to registrate online and then install the COPT package on your machine. If this is not done yet, please visit official COPT page and fill the registration form following the guidelines.

The online registration is for personal license application. Specifically, users only need to provide username of machine, besides basic information.

Upon approval, you will receive a letter from coptsales@shanshu.ai. It gives both link to download COPT software package and a license key tied with registration information. You may refer to Software Installation below and Setting Up License for further steps.

If you encountered any problems, please contact coptsupport@shanshu.ai for help.

Software Installation

Windows

We provide two types of installation packages for Windows operating systems, one is an executable installer for most of users and the other one is a zip-format archive specialized for expert users. We recommend users to download the excetutable installer.

If you download the executable installer for Windows from our website, e.g. CardinalOptimizer-6.0.0-win64-installer.exe for 64-bit version of COPT 6.0.0, just double-click it and follow the following guidance:

  • Step 1: Click the installer and select the installation language. The default installation language is English, users can change it by select from the drop-down menu, see Fig. 1. Here we use the default setting.

    _images/copt-winexe_langsel.png

    Fig. 1 Select installation language

  • Step 2: If you agree with the 'End-User License Agreement (EULA)', just choose 'I accept the agreement' and then click 'Next'. The software won’t install if you disagree with the EULA, see Fig. 2.

    _images/copt-winexe_eula.png

    Fig. 2 License agreement page

  • Step 3: By default, the installer will place all files into directory C:\Program Files\copt60, you may change it to any directories. If you have decided the install directory, just click 'Next', see Fig. 3.

    _images/copt-winexe_instdir.png

    Fig. 3 Choose install directory

  • Step 4: To select the start menu folder, you can simply use the default setting and click 'Next', see Fig. 4.

    _images/copt-winexe_startmenu.png

    Fig. 4 Select start menu folder

  • Step 5: By now, the software is ready to install, just click 'Install', see Fig. 5.

    _images/copt-winexe_install.png

    Fig. 5 Ready to install

  • Step 6: When installation completed, the software requires restart of your machine since the installer has automatically made the required modifications to environment variables for you. Be sure to save your working files and close other running applications before restart, and then click 'Finish', see Fig. 6.

    _images/copt-winexe_restart.png

    Fig. 6 Installation completed and restart your machine

If you downloaded the zip-format installer archive, just uncompress it to any directories with any unarchiver and set up environment variables as follows. Here we assumed the installation directory to be C:\Program Files\copt60:

  • Step 1: Open Command Prompt (cmd) with administrator priviledge and execute the following command to pop-up the environment variables setting panel.

    rundll32 sysdm.cpl,EditEnvironmentVariables
    
  • Step 2: Add directory C:\Program Files\copt60\bin to system environment variable PATH.

  • Step 3: Create a new system environment variable named COPT_HOME, whose value is C:\Program Files\copt60.

  • Step 4: Create a new system environment variable named COPT_LICENSE_DIR, whose value is C:\Program Files\copt60.

Up to now, you have already setup the required modifications to the environment variables. If you accept the copt-eula_en.pdf in installation directory, then please go to Setting Up License for license issues.

MacOS

We provide two types of installation packages for MacOS, one is a DMG-format installer for most of users and the other is a gzip-format archive for expert users. We recommend users to download the DMG-format installer.

DMG installer

If you download the DMG-format installer for MacOS from our website, e.g. CardinalOptimizer-6.0.0-osx64.dmg for 64-bit version of COPT 6.0.0, please follow the following guidance to install the software:

  • Step 1: Double-click the DMG-format installer, waiting for the OS to mount the DMG installer automatically.

  • Step 2: Simply drag the copt60 folder into 'Applications' folder, see Fig. 7:

    _images/copt-macdmg_dragfolder.png

    Fig. 7 Drag copt60 into 'Applications'

GZIP installer

If you download the gzip-format installer archive, just uncompress it to any directories with commands:

tar -xzf CardinalOptimizer-6.0.0-osx64.tar.gz

You will get a folder named copt60 in current directory, you can move it to any other directories as you want. We recommend users move it to the 'Applications' folder by executing commands below:

mv copt60 /Applications/

BASH terminal

The next step for both DMG-format and gzip-format installer is to setup the environment variables by adding the following commands to the '.bash_profile' file in your $HOME directory using any editors that you prefered:

_images/copt-mac_installenv.png

Remember to save your modifications to the '.bash_profile' file, if it does not exist, you can create at your own by executing:

touch ~/.bash_profile

ZSH terminal

If your terminal is zsh, you should add the following line to '.zshrc' file in $HOME directory as well:

source ~/.zshrc

Verify environment variable configuration

Now open a new terminal to check if the previous modifications work by executing commands below respectively:

echo $COPT_HOME
echo $COPT_LICENSE_DIR

echo $PATH
echo $DYLD_LIBRARY_PATH

If the terminal outputs respectively:

/Applications/copt60
/Applications/copt60
/Applications/copt60/bin:$PATH
/Applications/copt60/lib:$DYLD_LIBRARY_PATH

It means that the COPT-related environment variables are configured successfully.

Notes: The environment variables $PATH and $DYLD_LIBRARY_PATH may display different contents on different computers. However, the set COPT-related environment variables should be displayed normally to indicate that the configuration is successful.

If the user checks that the COPT-related environment variables have been successfully added, please carefully read the user agreement document 'copt-eula_cn.pdf' in the installation directory. If you accept the the agreement, please go to Setting Up License for license issues.

MacOS Security Checkup

For MacOS 10.15 (Catalina), if users received error message below:

"libcopt.dylib" cannot be opened because the developer cannot be verified.
macOS cannot verify that this app is free from malware.

or

"libcopt_cpp.dylib": dlopen(libcopt_cpp.dylib,6): no suitable image found.
Did find: libcopt_cpp.dylib: code signature in (libcopt_cpp.dylib) not valid
for use in process using Library Validation: library load disallowed by
system policy.

Then execute the following commands:

xattr -d com.apple.quarantine CardinalOptimizer-6.0.0-osx64.dmg
xattr -d com.apple.quarantine CardinalOptimizer-6.0.0-osx64.tar.gz

or

xattr -dr com.apple.quarantine /Applications/copt60

to disable security check of MacOS.

Linux

For Linux platform, we provide gzip-format archive only, if you download the software from our website, e.g. CardinalOptimizer-6.0.0-lnx64.tar.gz for 64-bit version of COPT 6.0.0, just type commands below in shell to extract it to any directories:

tar -xzf CardinalOptimizer-6.0.0-lnx64.tar.gz

You will get a folder named copt60 in current directory, you can move it to any other directories as you like. We recommend users move it to '/opt' directory by typing commands below in shell:

sudo mv copt60 /opt/

Note that the above command requires root privilege to execute.

The next step users need to do is to set the required environment variables, by adding the following commands to the '.bashrc' file in your $HOME directory using any editors that you prefered:

_images/copt-linux_installenv.png

Remember to save your modifications to the '.bashrc' file, and open a new terminal to check if it works by executing commands below respectively:

echo $COPT_HOME
echo $COPT_LICENSE_DIR

echo $PATH
echo $LD_LIBRARY_PATH

If you accept the copt-eula_en.pdf in installation directory, then please go to Setting Up License for license issues.

Setting Up License

The Cardinal Optimizers requires a valid license to work properly. We offer different types of licenses most suitable for user’s needs. All users should read this section carefully. If you encounter any problem about license, feel free to contact coptsupport@shanshu.ai.

Once the registration is done, a license key is sent to users. It is a unique token binding with user’s registration information. Afterwards, users may run the copt_licgen tool, shipped with Cardinal Optimizer, to obtain license files from COPT licensing server (Internet connection required) .

The following notes show you how to play with the copt_licgen tool.

Obtaining License

For Windows system, open a new cmd window. The current path is the user directory, and the path is as follows: "C:\Users\shanshu".

For MacOS and Linux systems, open a new terminal. The current path is the user directory, represented by the symbol ~.

To obtain COPT license files, execute the following command using the option '-key' and the license key as argument. Below is an example, assuming the license key is '19200817f147gd9f60abc791def047fb':

copt_licgen -key 19200817f147gd9f60abc791def047fb

If the license key is saved to key.txt file in format of 'KEY=xxx', which resides in the same place as copt_licgen, execute the following command using the option '-file' and 'key.txt' as arugment.

copt_licgen -file key.txt

We recommend to use the first way to get your license files.

If the authorization server verifies the license, then it generates license.dat and license.key and download it to the user’s computer. The default download directory is the current working directory.

copt_licgen -key 19200817f147gd9f60abc791def047fb
  [Info] Cardinal Optimizer   COPT v6.0.0 20221010
  [Info] Use specific key 19200817f147gd9f60abc791def047fb
  [Info] * get new COPT license from licensing server *
  [Info] Write to license.dat
  [Info] Write to license.key
  [Info] Received new license files from server
  [Info] Done !!!

Note: Users do not need to have internet connection to run COPT. However, obtaining license itself requires internet connection. If you encounter any problem, please feel free to contact coptsupport@shanshu.ai.

Verifying License

If the license key binding to registration information is verified by COPT license server, two license files, license.dat and license.key, are downloaded to the current working directory. To double check two license files are valid in current version of COPT, execute the following command with the option '-v'. Note that this command requires both license.dat and license.key existing in the current working directory.

copt_licgen -v

If you see log information similar to the following, you have obtained and verified the license files sucessfully.

copt_licgen -v
  [Info] Cardinal Optimizer   COPT v6.0.0 20221010
  [Info] Run local validation
  [Info] Read license.dat
  [Info] Read license.key
  [Info] Expiry : Tue 2030-12-31 00:00:00 +0800
  [Info] Local validation result: Succeeded
  [Info] Done !!!

Installing License

Once you obtained the license.dat and license.key files from COPT license server and verified they work as expected, setting up them is just as simple as moving them to the same directory as the COPT dynamic libary or COPT Command-Line. Note this installation is applied only to current COPT.

The following two ways of installation applied to all versions of COPT on your machine.

Via environment variable method

Alternatively, for users who prefer having licenses in a customized folder, they can set environment variable COPT_LICENSE_DIR to the customized folder. You may refer to Software Installation for how to set environment variable on Windows, Linux and MacOS.

In addition, please double check that if license files license.dat and license.key locate in path specified by environmental variable COPT_LICENSE_DIR.

The viewing and operation of environment variables are slightly different under different systems, please refer to the following installation steps for your own operating system:

Windows

For Windows systems, execute the following command to view the path pointed to by the environment variable COPT_LICENSE_DIR :

echo %COPT_LICENSE_DIR%

Note: If there is no output on the terminal, it means that the COPT-related environment variables have not been configured, please check Software installation.

Then move the license files license.dat and license.key to the path COPT_LICENSE_DIR points to.

Here we assume that the environment variable COPT_LICENSE_DIR points to the default installation directory of COPT. As shown in the figure, it means that the license has been installed correctly:

_images/copt-win_license2.png

MacOS

For MacOS system, you can use the following command to view the path pointed to by the environment variable COPT_LICENSE_DIR:

echo $COPT_LICENSE_DIR

Then move the license files license.dat and license.key to the path COPT_LICENSE_DIR points to.

Here we assume that the environment variable COPT_LICENSE_DIR points to the default installation directory of COPT. As shown in the figure, it means that the license has been installed correctly:

_images/copt-mac_license2.png

Linux

For Linux systems, user can use the following command to view the path pointed to by the environment variable COPT_LICENSE_DIR:

echo $COPT_LICENSE_DIR

Then user can execute the following command to move the license files license.dat and license.key to to the path COPT_LICENSE_DIR points to.

mv license.* $COPT_LICENSE_DIR/

Note: For Linux systems, if the path pointed to by the environment variable COPT_LICENSE_DIR is /opt/copt60, user need to perform the move operation with root authority , and the command is:

sudo mv license.* $COPT_LICENSE_DIR/

In addition, please double check that if license files license.dat and license.key locate in path specified by environmental variable COPT_LICENSE_DIR , and the command is:

ls $COPT_LICENSE_DIR/

If the terminal displays the files license.dat and license.key, it means that the license has been installed correctly, otherwise the license installation fails.

Note: If there are license files license.dat and license.key in the copt folder of the user directory and the directory pointed to by the environment variable, the former will be checked and used the former.

Others

Basically, each type of licenses includes two license files: license.dat and license.key, each of which has digital signature to protect its content. When invoking COPT command-line or loading COPT dynamic library to solve an optimization problem, the public RSA key stored in 'license.key' is used to verify signature in 'license.dat'.

Afterwards, license data in format of key-value pair is parsed to verify whether it is a legal license. Below is a sample of license data.

## SHANSHU LICENSE FILE ##

USER = Trial User
MAC = 44:05:99:31:41:C2
CPUID = BFEBFBFF000706E5
EXPIRY = 2030-12-31
VERSION = 6.0.0
NOTE = Free For Trial