PINS installation

PINS is supported in the three main OS: Windows, Mac OSX and Linux. We are also deploying PINS for some ARM architectures with Linux OS, but is still sperimental. To run PINS you need a Maple 2016 or higher, a C++ compiler. Therefore you have to install Maple and a supported C++ compiler before installing PINS. Supported compilers and additional prerequistes are listed for each OS below. Additionally, you need to install Matlab 2017 or higher in case you want to use PINS with the Matlab interface.

Windows

Windows installation pre-requisite

PINS needs a compiler and under windows the VisualStudio 2017 is the only supported compiler (but 2015 and 2019 shuold work as well). Install the free version Visual Studio Community 2017.

If PINS is used from the terminal it is first necessary to execute the vs2017.bat command that comes with the installer and setup the path to use the VS from the terminal (for 2105 and 2019 use vs2015.bat or vs2019.bat respectively). With the new release of PINS the script is executed automatically by the installer.

Additionally we suggest to install chocolatey a package manager for windows

Then install the following packages from terminal:

  • ruby with command choco install ruby

  • cmake with command choco install cmake

  • Visual Studio Code with command choco install visualstudiocode

and optionally

  • ConEmu with command choco install conemu

  • YAML with command choco install yaml

Windows installation of PINS

There are two installers for PINS.

  • MapleXOptimaLink-x.x.x-dxxxdirty-windows_10.0_x64.exe

  • PINS-x.x.x-dxxxdirty-windows_10.0_x64-MSVC2017.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

  • run first MapleXOptimaLink-x.x.x-dxxxdirty-windows_10.0_x64.exe this operation must be done only ONCE or when Maple is changed, reinstalled or updated. This must be run with administrator privilege and creates a symbolic link with 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. See Figures Maple XOptima Package installer window

../_images/install_01.png

Maple XOptima Package installer window

../_images/install_02.png

Maple XOptima Package installer: select your correct destination folder

  • run the installer PINS-x.x.x-dxxxdirty-windows_10.0_x64-MSVC2017. 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 is installed in Toolbox folder of the most recent Maple version installed in your computer. In case you have more versions of Maple, in order to use XOptima also in those, you have to manually copy the package in the Toolbox folder of the less recent Maple versions. See Figures Mechatronix Library installer window.

../_images/install_03.png

Mechatronix Library installer window

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

$ pins -i

It should print a message similar to :

 ____  ___ _   _  ____
|  _ \|_ _| \ | |/ ___|
| |_) || ||  \| |\___ \
|  __/ | || |\  | ___) |
|_|   |___|_| \_||____/

Mechatronix library version: 1.4.5-d212dirty-osx_10.15.6
commit #g06adfde3
pins library search path:
  [".", "./mrblib", "/Library/Frameworks/MechatronixInterfaceMruby.framework/Resources/mrblib"]

License status:
  Maple XOptima:  not available
  Mechatronix:    not available

To generate the necessary information see Getting License for PINS.

You will receive back a file <host-name.XoptimaLicense.dat>: rename and copy it to the folder C::PINS

copy host-name.XoptimaLicense.dat XOptimaLicense.dat

To test that the library is correctly installed in a command window write, see Figures Library version check and License data generation:

pins -i

It should print a message similar to :

 ____  ___ _   _  ____
|  _ \|_ _| \ | |/ ___|
| |_) || ||  \| |\___ \
|  __/ | || |\  | ___) |
|_|   |___|_| \_||____/

Mechatronix library version: 1.4.5-d212dirty-osx_10.15.6
commit #g06adfde3
pins library search path:
  [".", "./mrblib", "/Library/Frameworks/MechatronixInterfaceMruby.framework/Resources/mrblib"]

License status:
  Maple XOptima: available
  Mechatronix:   available
../_images/install_04.png

Library version check

../_images/install_05.png

License data generation

Unix/Linux

Install the prerequisite packages with the command line:

$ sudo apt-get install build_essentials

Install the library

The installation of PINS is pretty straight forward under Linux since you need to just run the installer. Here anm example (modify the installer version with the nwest one available):

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

# optionally fixes the dependencies
$ sudo apt-get install -f

The installer (shuold) also downloads and installs all the necessary components.

To generate the necessary information see Getting License for PINS.

You will receive back a file <host-name.XoptimaLicense.dat>: rename and copy it to your home folder as follows:

$ cp host-name.XoptimaLicense.dat ~/.XOptimaLicense.dat

To test that the library is correctly installed in a command window write:

$ pins -i

#You should get:

$ Mechatronix library version: beta-1.0-<...>
$ commit #...

$ Maple XOptima:  available
$ Mechatronix:  available

Installation of Ruby and suggested gems (optional)

PINS comes with embedded ruby therefore there is no need of another scripting language. In case you want to call PINS 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

MacOSX

PINS needs a compiler and under MAC OSX clang Xcode is the supported compiler.

MAC OSX installation pre-requisite

Additionally we suggest to install Homebrew (a package manager for MAC OSX) to install the following prerequisite packages from terminal:

With Brew you can easily install the other required packages:

$ brew install cmake
$ brew install libyaml

Installation of Ruby and suggested gems (optional)

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 Mac 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 installer 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. In case you have more versions of Maple, in order to use XOptima also in those, you have to manually copy the package in the Toolbox folder of the less recent Maple versions.

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

$ pins -i

It should print a message similar to:

 ____  ___ _   _  ____
|  _ \|_ _| \ | |/ ___|
| |_) || ||  \| |\___ \
|  __/ | || |\  | ___) |
|_|   |___|_| \_||____/

Mechatronix library version: 1.4.5-d212dirty-osx_10.15.6
commit #g06adfde3
pins library search path:
  [".", "./mrblib", "/Library/Frameworks/MechatronixInterfaceMruby.framework/Resources/mrblib"]

License status:
  Maple XOptima:  not available
  Mechatronix:    not available

You get the not available License status since now you need to get a valid licence.

To generate the necessary information see Getting License for PINS.

You will receive back a file <host-name.XoptimaLicense.dat>: rename and copy it to your home folder as follows:

$ cp host-name.XoptimaLicense.dat ~/.XOptimaLicense.dat

To test that the library is correctly installed in a command window write:

$ pins -i

#You should get:

$ Mechatronix library version: beta-1.0-<...>
$ commit #...

$ Maple XOptima:  available
$ Mechatronix:  available

Getting License for PINS

Once you have installed PINS you need to ask for a valid licence file. To get it first you have to open a terminal and write

pins -g

This command will create a file, typically in the user directory, with name YourHostName*_XoptimaDataForLicense.dat where *YourHostName is the host name of your computer. The file has to be sent to or . We will generate the licence file that will be sent you along with instructions.