How to install PINS

PINS is supported in the three main OS: Windows 10, MAC OSX and Linux. PINS runs also for some ARM architectures with Linux OS, but is still sperimental and user may ask for versions on specific target OS and architecture. To run PINS you need to install the followings before installing PINS:

  • a Maple© installation such as Maple 2016 or higher

  • a supported C++ compiler. Supported compilers and additional prerequisites are listed below for each OS.

  • optionally, you need to install Matlab 2017 or higher in case you want to use PINS with the Matlab interface.

Installing PINS unders MAC OS

MAC OSX installation pre-requisite

PINS needs a compiler and under MAC OSX clang Xcode is the supported compiler. Additionally, we suggest to install Homebrew (a package manager for MAC OSX) to install the cmake command:

   brew install cmake

cmake can be used to compile the C++ project. PINS automatically generate a CMakeList.txt file to compile a pure C++ program.

PINS comes with mruby therefore there is no need of another scripting language. In case you want to call PINS from Ruby it is still possible and we suggest to install the following gems: colorize, yard, yaml, erubis, pry, ffi, zip, zlib, uri, openssl, fpm. Ruby is part of the OSX but user cant install gems globally. Thus each user can install additional ruby gems only locally:

    gem install --user-install colorize
    gem install --user-install yard
    gem install --user-install yaml
    gem install --user-install erubis
    gem install --user-install pry
    gem install --user-install ffi
    gem install --user-install zip
    gem install --user-install zlib
    gem install --user-install uri
    gem install --user-install openssl
    gem install --user-install fpm

OSX installation of PINS

Now you are ready to install PINS with the installer. We suggest to use the laster version available PINS-x.x.x-dxxxdirty-osx_10.15.7.mpkg. Just click on the installer and follow the instructions. The program also installs the XOptima Package for Maple© to formulate the optimal control problem and automatically generete the C++ code. The package is installed in Toolbox folder of the most recent Maple© version installed in your computer.

Warning

In case you have more versions of Maple© installed in your computer, PINS installer does not install XOptima in all Maple© installations and the user must do it manually by compying the XOptima package in the Toolbox folder of the all Maple© installations.

To check the installation is succesfull, write on the terminal:

   pins -i

It should print a message similar to :

    ____ ___ _   _  ____
   |  _ \_ _| \ | |/ ___|  (P)ins
   | |_) | ||  \| |\___ \  (I)s
   |  __/| || |\  | ___) | (N)ot a
   |_|  |___|_| \_||____/  (S)olver
   
   version: 1.5.7-d016dirty-osx_14.6.1
      date: Wed Sep 25 21:08:48 2024
    commit: #da3637cb4370f4f4a37f350f535c9bf9a32ef0cf-dirty
      path:
     .
     ./mrblib
     /Library/Frameworks/MechatronixInterfaceMruby.framework/Resources/mrblib
   license: (expire:0 days left) (devkit:off) (pins:off) (runtime:off)

You get the expire:0 days left License status since you still need to get or activate a valid licence. Follow the steps in the License activation section.

Installing PINS unders LINUX

The installation of PINS is pretty straight forward under Linux since you need to just run the installer. Here below an example ( use the installer name of the version that you have):

	# Linux installation of PINS
	sudo dpkg -i PINS-linux_Ubuntu_18.04.5_LTS-1.4.5-d190dirty_amd64.dev

The installer also downloads and installs all the necessary components including the gcc compiler and :red:DA COMPLETARE

PINS comes with embedded ruby therefore there is no need of another scripting language. In case you want to call PINS from Ruby it is still possible and we suggest to install the following gems:

   gem install colorize yard yaml erubis
   gem install pry ffi zip zlib uri openssl fpm

Installing PINS unders WINDOWS

Windows installation pre-requisite

PINS needs a compiler and under windows the VisualStudio 2019 is the only supported compiler (but higher version should work as well up to Visual Studio Community 2022). Install the free version Visual Studio Community 2019.

Warning

In order pins command can compile the source code it has to be launched from the Visual Studio Developer Command Prompt, which is a standard command prompt with certain environment variables set to make using command-line developer tools easier. This can be done manualy but PINS installation cames with a set of scripts (e.g. vs2019.bat, vs2022.bat, etc) that setup the path to use the VS from the proper Visual Studio Developer Command Prompt. Those scripts assume that VS is installed in C:\\Progam Files\. In case this is not the case you must change them manually and write the correct Visual Studio installation folder.

Additionally, we suggest to install chocolatey a package manager for windows

Then install the cmake and Ruby from terminal:

   choco install ruby
   choco install cmake

In case the command are not found, refresh the environment with the command

   refreshenv

and install the colorize gem :

   gem install colorize

and optionally ConEmu and YAML:

   choco install conemu
   choco install yaml

Windows installation of PINS

Under windows there are three installers to be launched in sequence (names may differ based on the release)

  • PINS_link-1.0.3-d000-windows_10.0_x64.exe

  • PINS_XOptima_link-1.0.3-d000-windows_10.0_x64.exe

  • PINS-1.0.3-d000-windows_10.0_x64-MSVC2019.exe

The support for MKL is currently discontinued but will be fixed soon. At present PINS support only openBlas linear Algebra libraries.

For the installation launch the following with the order in the list:

  • PINS_link-1.0.3-d000-windows_10.0_x64.exe. This operation must be done only ONCE at the first installation. This must be run with administrator privileges and creates a symbolic link to a local installation of PINS in the user home directory. Therefore you can also install PINS in a location different than the default one. When you update PINS to new releases it is not necessary to launch again this executable.

  • PINS-1.0.3-d000-windows_10.0_x64-MSVC2019.exe. Just click on the installer and follow the instructions. The installer also installs the XOptima package for Maple© to formulate the optimal control problem and automatically generete the C++ code. The package should be installed in Toolbox folder of the most recent Maple© version installed in your computer. However, under Windows it is installed in the PINS installation folder and a symbolic link is created between Maple© Toolbox folder XOptima package folder in PINS installation folder. The link is created by PINS_XOptima_link<...> installer. In case you have more versions of Maple© and you want to XOptima also in those, you have to manually copy the package in the Toolbox folder of the less recent Maple© versions or create the symbolic link that points to the XOptima package folder in PINS installation folder.

  • PINS_XOptima_link-1.0.3-d000-windows_10.0_x64.exe. This operation must be done only ONCE or when Maple© is changed, reinstalled or updated. It has to be done after PINS is installed. This must be launched with administrator privileges and creates a symbolic link in the Maple© toolbox to a local installation of PINS in the user home directory. When you update PINS to new releases it is not necessary to launch again this executable.

To check the installation is succesfull, write on the terminal:

	pins -i

It should print a message the following message:

    ____ ___ _   _  ____
   |  _ \_ _| \ | |/ ___|  (P)ins
   | |_) | ||  \| |\___ \  (I)s
   |  __/| || |\  | ___) | (N)ot a
   |_|  |___|_| \_||____/  (S)olver
   
   version: 1.5.7-d016dirty-osx_14.6.1
      date: Wed Sep 25 21:08:48 2024
    commit: #da3637cb4370f4f4a37f350f535c9bf9a32ef0cf-dirty
      path:
     .
     ./mrblib
     /Library/Frameworks/MechatronixInterfaceMruby.framework/Resources/mrblib
   license: (expire:0 days left) (devkit:off) (pins:off) (runtime:off)  
   (C) 2024 Bertolazzi, Biral, Bosetti (University of Trento)

You get the expire:0 days left License status since you still need to get or activate a valid licence. Follow the steps in the License activation section.

License activation

Once the software is installed it has to be activated with a valid license file.
Donwload the license file from your Cryptlex account (Cryptlex ) and copy it on the PINS installation folder which should be C:\USERNAME\PINS where USERNAME is a place holder for the name of the user. You can also copy the licence file in the right place using the following terminal command:

	pins -s LICENCE_KEY_STRING

where LICENCE_KEY_STRING is the string of the licence key (typically is the name of the licence file) that you downloaded from your Cryptlex account. The command first tries to copy the license in the folder C:\PINS\ and if it does not succeeed it installs in C:\USERNAME\PINS where USERNAME is a place holder for the name of the user.

Then activate the license running the following command on the terminal

  pins -a

Other useful commands to manage the license are the following:

Options: -h,–help Print this help message and exit [Option Group: license and documentation]

To activate a licence located at ${HOME}/.PINS.key:

	pins -a

or

	pins --activate

To deactivate the license in the current machine:

	pins -d

or

	pins --deactivate

To activate a trial version:

	pins -t

or

	pins -trial

To activate the license using key-string:

	pins -s TEXT

or

	pins --license_string TEXT

where TEXT is the license key.

After the activation you can check the license status using the command:

	pins -i

It is possible to activate and deactivate the software for a limited or unlimited number of times depending on your license. In case you need this feature write pins info with your questions.

The command pins --check_license can be used to check the license status. If the license is active the command will return the string active

	pins --check_license
	# output should be `active`