MonolixSuite2016R1 installation and administration guide

1.Prerequisites

MonolixSuite2016R1 has a standard installation process and thus has only few or no prerequisites depending on your operating system.

Windows specifics
No prerequisite.

Linux specifics
Make sure you have gcc/g++/make installed or install them.

Mac OS X 10.6 or higher specifics
– install and launch   at least once Xcode, in order to being able to compile any C++ code  on your computer.
– install  XQuartz (or X11 for osX < 10.7), close and restart your session at least once after the installation, in order to make the  system  recognize the path of X11.
These  operations must be done after any update or upgrade of your system.  XQuartz can be founded on Apple’s website, Xcode can be installed  using  App Store.app.

Possible needs

  • Monolix is provided with a stand alone application. However, it can be also run using Matlab.
  • Perl is needed to run perlScripts and the Monolix validation suite; it is not required otherwise.

2.About the installer

Windows

  • copy the installer on your Desktop or in your windows temporary directory,
  • double click on the executable and follow the instructions. The instructions are very simple and will allow you to define the installation folder, the shortcut menu name, …

Linux

The installer is an executable.

  • copy the installer on your Desktop or in a temporary directory,
  • double click on the executable and follow the instructions. The instructions are very simple and will allow you to define the installation folder, the shortcut menu name, …

License

At the end of the installation, during the initialization, the license activation process occurs. Notice that the license is independent of the software version, e.g. if you have a valid license for Monolix 4.3.2,
– you can install MonolixSuite2016R1 too,
– your Monolix license will be valid for Monolix2016R1 too.

During the initialization process, the installer will check if you already have a license. If not, a window will pop up requesting an activation key, or a licence file. If you do not have it, just click on the cross to cancel it. Two things have to be noticed:
– If you do not have a valid license key, the software will be installed and you will be able to re-activate it later.
– If your license key is valid for several software and/or for the MonolixSuite, the license request will be done for the first software and will automatically be validated for the other one.

3.MonolixSuite directory structure

The MonolixSuite2016R1 directory structure is divided in two parts:

  • the software directory containing the MonolixSuite applications (/Path/To/MonolixSuite2016R1)
  • the personal user directory containing the MonolixSuite2016R1 workspace  (<USER>/lixoft)

Installation directory

  • bin: Tools directory. It corresponds to the directory where all software are launched.
  • config: Configuration files. It corresponds to the reposetory where preferences and configuration are defined for all software.
  • factory: Mlxtran C++ API and library. It corresponds to all Mlxtran model libraries (pk, pke, pd, pde) and to all the C++ API to run Mlxtran model.
  • install: Icons. It contains all the icons for Lixoft software.
  • jar: java libraries
  • lib: C++ libraries
  • Licenses: Terms of uses. It corresponds to the term of uses of Lixoft software.
  • matlab: Monolix main program
  • perlScripts: Perl scripts. It is used for the validation suite for Monolix.
  • ressources: documentation and demos. It corresponds to all the demos for all the software. It is copied in the user folder when running a software.

User directory
The user directory is created after the first launch. It contains

  • in file /lixoft/lixoft.ini: the path of the different installed Lixoft products
  • one sub-directory per software.This directory contains the
    basic configuration of the software, demos, log files, license file, …
  • a licence directory where the licence is kept.

Each sub-directory has the same folders

  • a configuration directory where the preferences and the configuration of the user are kept. It is created at the first use of the software and initialized from the configuration in the installation folder.
  • a licence directory where the licence is kept.
  • a 2016R1 folder that contains the demos, the log files, the modules (compiled Mlxtran modules), and the temporary files.

Notice that having the configuration folder outside the 2016R1 folder allows the user to keep its configuration from a version to another one.

4.License type and use

License type

MonolixSuite2016R1 licenses can be of the following types:

  • Individual license – named user. The named user can install and run MonolixSuite2016R1 on a computer.
  • Server license – concurrent access. MonolixSuite2016R1 run on an application server and a predetermined number of users can use it at the same time.
  • Floating license – concurrent access. The license is hosted by a license server, and MonolixSuite2016R1 can either run on a server or individual workstations.

In any case, a license key number or file is generated. Notice that the license request is only done when no license is available on the user’s computer or when the license expires.
Two folders are key {MonolixSuite2016R1}/config/system/access and {MonolixSuite2016R1}/bin/Monolix_mcr/runtime/config/system/access, where  {MonolixSuite2016R1} corresponds to the directory where MonolixSuite 2016R1 is installed. In the following, these folders will be refereed as KeyFolder1 and KeyFolder2 respectively.

Individual license

The activation key (provided by Lixoft) must be entered in the dialog box titled “Lixoft license activation” (“With activation key” tab).

Licence

In that case, the license is copied into {UserName}/lixoft/license. The dialog box only appears when no license is available on the user’s computer or when the license expires. Our software is available with independent licenses for Mlxplore, Monolix and Simulx if you just need a particular product. We also propose a license for the Monolix Suite for you to take full advantage of the integrated visualisation, modelling and simulation features.

When do I need an individual license ?

Two main cases

  • when the user accesses to MonolixSuite with its own computer
  • when the user accesses to MonolixSuite through a remote access and wants its own dedicated license.

Server license

In that case, MonolixSuite runs on an application server. The activation key (provided by Lixoft) must be copied into the following folders of the server: KeyFolder1and KeyFolder2.
With that, each time a user starts an application of MonolixSuite, it takes a token from the license for the application under consideration. If all tokens are used (too many users use the software), a popup titled “Lixoft activate” appears and the user is supposed to add its own license or buy other licenses to increase the number of tokens for the server license.

When do I need a server license ?

Two main cases

  • when the user accesses to MonolixSuite through a remote access. In that case, all the license management is defined by the IT.
  • when the user accesses to MonolixSuite through a shared directory (via CIFS, Network drive, NFS, …). In that case, if the IT provides Lixoft with all the MAC address of the users, Lixoft can provide a dedicated license key to the IT in order the user not to have to provide a license key when running.

Floating license

The use of a floating license requires to set up a license server. Two utilisations are possible:

  • when the user accesses to MonolixSuite with its own computer and just need a license that points toward the license server. In that case, the IT provides the user a license key (using the license server management system)  to copy it into {UserName}/lixoft/license folder,
  • when the user accesses through a remote access or a shared directory. Then, the license key is provided by the IT (using the license server management system) and should be copied into KeyFolder1and KeyFolder2.

The setup and configuration of the license server is described here.

Roaming license

RLM has the ability to allow a floating license to roam to a system which will subsequently be disconnected from the network for a short period of time. The resulting license can be used for the number of days specified when the license was set to roam, and is checked back in automatically at the end of this. In addition the user can return the roamed license back to license pool early if this is desired. See License activate tools (which can be launched from the Monolix interface, in tools menu)

roaming

This feature is enabled on demand. An extra activation key will be provided by Lixoft and the procedure to get the roaming license feature is identical to the installation of a floating license. To enable this feature, the file system.xmlx (stored in both KeyFolder1 and KeyFolder2 directories) must be modified by setting to “on” the roaming option:

<?xml version="1.0" encoding="utf-8"?>
<monolix>
<preference>
<session>
<userPath windows="%USERPROFILE%" linux="$HOME"/>
<license activation="http://activate.lixoft.net" roaming="on"/>
</session>
</preference>
</monolix>

5.Floating licence management using RLM

The use of a floating license requires to set up a license server. After the installation process, when the “Lixoft activate window” appears just close the window (do not enter the activation key of the floating license). Then, download the RLM server here

Start the RLM server. At this step there is no license available yet; the IT manager should use the RLM web server to download the license by following the procedure below:

1/ In the web browser, type “IP”:5054, where “IP” is the IP address of the computer hosting the RLM server (e.g. 192.168.46.248:5054). Notice that the RLM server opens two ports : 5053 and 5054. The first port (5053) is a service port used for the transactions of licenses. The second port (5054) is the RLM web server port used to access to the RLM configuration through a web browser. It is possible that one or both ports may have been used by another application.

  • If the web server port (5054) is not available you can launch RLM server with a new port by using the program option -ws (e.g: rlm -ws 5055) in this case, the access to RLM configuration through a web browser is done using the address “IP”:”NEW PORT” (e.g. 192.168.46.248:5055).
  • If the server port (5053) is not available, a file config.conf has to be created in the rlm directory and has to contain the following information: HOST “IP” “MAC ADDRESS” “NEW PORT” e.g. HOST 192.168.46.245 a8c0f82e 5060

rlm1

2/ Begin license activation:

rlm2

3/ Enter the RLM activation url : activate.lixoft.net. And click on Next button. If the rlm server does not have Internet access, the license has to be created by Lixoft. Send a mail to support@lixoft.com with the following informations:

  • Mac address of the computer hosting the RLM server
  • IP address of the computer hosting the RLM server

rlm3

Lixoft will send in return a ’.lic’ file which has to be copied in the following directories: KeyFolder1 and KeyFolder2. At this step, the installation of MonolixSuite2016R1 is complete.

4/ Activate the license. Fill the ISV input with the string “lixoft” (without the quotes) and the License activation key with the activation key provided by Lixoft (key format is xxxx-xxxx-xxxx-xxxx)

rlm4

5/ Enter (at maximum) the number of bought licenses, then click on Next button. Notice, the number of licenses cannot exceed the number of bought licenses.

rlm5

6/ Select the license directory and file. In the field named License file to create write the full path to license file  KeyFolder1/myfloat.lic and copy it to KeyFolder2 e.g: if the MonolixSuite2016R1 installation directory is /media/share/MonolixSuite2016R1, the input field name License file to create should contain /media/share/MonolixSuite2016R1/config/access/myfloat.lic. This license file has to be copied on each installation of MonolixSuite2016R1 :

  • If Monolix is installed on a shared space (i.e. each node of the cluster has an access to this directory), copy the license file into the directories KeyFolder1 and KeyFolder2. Make sure that the MonolixSuite2016R1 directory is accessible from each cluster node.
    Example
– Monolix is installed on the computer master-computer in the directory:
/usr/local/lixoft/MonolixSuite2016R1/.
The license is in the directory :
/usr/local/lixoft/MonolixSuite2016R1/config/access/
– The RLM server is run on the computer master-computer.
– Cluster computers mount the directory /usr/local/lixoft/MonolixSuite2016R1/.
– Each MonolixSuite2016R1 user runs Lixoft software from the previously mounted directory.
  • If Monolix is installed on each node of the cluster, copy the license file on each computer in the directories  KeyFolder1 and KeyFolder2.
    Example
– The RLM server is executed on the computer master-server.
– Monolix is installed on each cluster node of the cluster.
– The license file is copied on each cluster node in the directory /MonolixSuite2016R1/config/system/access/ 
and /MonolixSuite2016R1/bin/Monolix_mcr/runtime/config/system/access
for the standalone version.
– Each MonolixSuite2016R1 user runs Lixoft software from the cluster node.

rlm6

7/ Stop the server manually and restart it from the directory (or use option -c) {MonolixSuite2016R1}/config/system/access/

Now RLM is running with the provided license. This is verified in the web interface by clicking on status button.

rlm7

8/ RLM Server : server hostname and port considerations.
If for any reason, the server port or the server hostname is not registered in a DNS, it is possible to change these informations directly on licence file. The line HOST can be changed by HOST .

9/ RLM Server : firewall considerations.
If the RLM server is behind a firewall, the port 5053, 5054 and the ISV port have to be opened.
The ISV port can be set directly in license file by changing the ISV line as follow:

...
ISV lixoft port=
...

10/ Managing RLM server:
The documentation of the management of the RLM server provided by Reprise Software is available at http://www.reprisesoftware.com/RLM_Enduser.html

6.How to see that the applications are well installed ?

Datxplore

  1. Open Datxplore
  2. Go to the menu Project/Load demo as on the following figure
    datxplore1
  3. A window with all the demos for Datxplore pops up. Then, choose the file theophylline.datxplore.mlxtran and click on open.
  4. Datxplore should load the project and display the data set like on the following figure. datxplore2

 

Mlxplore

  1. Open Mlxplore
  2. Go to the menu Project/Load demo as on the following figure
    mlxplore1
  3. A window with all the demos for Mlxplore pops up. Then, choose the file TumorGrowthModel.mlxplore.mlxtran in the folder CaseStudies\TumorGrowthInhibitionModel\ and click on open.
  4. Mlxplore should load the project and display the model like on the following figure.mlxplore2
  5. Run the project bu clicking on the arrow (in the green circle). The computation will run and the following figure should be displayed mlxplore3

 

Monolix

  1. Open Monolix
  2. Go to the menu Project/Load
  3. If it is your first launch of Monolix, there is no historic. Thus, you should go to YourUsername\lixoft\monolix\monolix2016R1\demos\theophylline\theophylline_project.mlxtran. Otherwise, click on « Browse demo » to open the theophylline_project.mlxtran demo in the theophylline folder. In both cases, a window of the project summary will pop up as the following figure and click on « Open » (in the green rectangle).
    Monolix1
  4. Monolix loads the project and the interface looks like the following figure MonolixTheoInstall
  5. The project is using data and a model defined in the green rectangle, and you can launch the workflow (in the presented case, the population parameter estimation, the Fisher Information Matrix calculation using linearization and the individual parameter estimation using the conditional modes) by clicking on the “Run” button (in the blue rectangle).
  6. Several progress bar showing the evolution of the tasks are displayed and at the end, some figures are displayed as in the following figure (in the presented case, the VPC is displayed). Monolix3

Simulx

Simulx is a little bit different from the other applications because it does not have yet a user interface. To validate it, one should use R (version greater than 3.0.2) to run simulations.

  1. Open R or Rstudio
  2. The R-packages needed to run Simulx are defined here. Make sure you have all the required packages.
  3. Execute the following commands
    # Define the mlxR library
    library("mlxR")
    # Define the model
    myModel <- inlineModel("[LONGITUDINAL]
    input = {V, Cl}
    EQUATION:
    Cc = pkmodel(V, Cl)")
    # Define the administration
    adm <- list(time=3, amount=40)
    # Define the output
    Cc <- list(name='Cc',time=seq(from=0, to=20, by=0.1))
    # Run the simulation
    res <- simulx(model=myModel, parameter=c(V=10, Cl=4), output=Cc,treatment=adm)
    # Plot the concentration w.r.t. time
    print(ggplot(data=res$Cc, aes(x=time, y=Cc)) + geom_line(size=1))
    
  4. The computation is launched and the following graphic appears Simulx2

7.Troubleshooting

Downloading MonolixSuite

Problem: My web browser claims that the Monolix download website has insufficient reputation and suggests to stop the download.
Solution: Some browsers like Google Chrome and Internet Explorer may ask whether to keep or remove the MonolixSuite archive just after download because of the insufficient reputation of the Lixoft website, simply because it is unsifficiently referenced. Please ignore the warning and choose to keep the file. You can use a MD5 tool to verify that the downloaded file is not corrupted.

Problem: The MonolixSuite archive is removed just after being downloaded.
Solution: Some antivirus may consider the MonolixSuite archive as risky and put it in quarantine or remove it. This is due to the fact that MonolixSuite embeds a compiler for the Mlxtran language. Two solutions are available:

  1. Deactivate your antivirus auto-protection process during download and installation, or
  2. Restore the file from the quarantine.

To restore the file from quarantine, please refer to the documentation of your antivirus software.
For the most common examples:

  • Norton Antivirus 2012: Start Norton Antivirus and Choose Advanced, then Quarantine
  • Avast Antivirus 7: Open Avast, Choose Maintenance, then Virus Chest

You should see the downloaded file among the quarantined files. Execute the Restore action; the archive will be restored into the directory used for downloading. Click on the archive (ignore a possible “malware” warning, again related to the fact that MonolixSuite embers a compiler.), and installation will start.

Installing MonolixSuite

Problem: When launching the installer, my antivirus tells me that the executable file stopped working.
Solution: If your antivirus apparently stopped the execution, it is  just scanning the installation program. Thus, just “Close the program” and the installer will reopen automatically.

Running Monolix

Problem: When launching the standalone version, my antivirus tells me that the file mlxinitializer.exe is risky.
Solution: If your antivirus apparently removed the file mlxinitializer.exe, check if it was actually put on Quarantine, or removed. If it is in Quarantine, please restore it by following the same instructions as provided above. If the file was removed you will need to reinstall MonolixSuite. You should be able to add this file to your antivirus Trusted Zone or Trusted files.

  • Norton Antivirus 2012:
    • go to folder Lixoft/MonolixSuite2016R1/bin in installation directory then Quarantine (for ex. C:\ProgramData\Lixoft\MonolixSuite2016R1\bin)
    • right click on mlxinitializer.exe, click on Norton Antivirus, then Norton File Insight then look for ‘Unproven’, and click ‘Trust Now’.
  • Avast Antivirus 7:
    • This software may start Monolix in a SandBox, i.e in a zone where the antivirus avoids any modification of the system or the files. He will ask you what to do at each run. Select Run normally
    • You can also add mlxinitializer.exe to the exclusions in its Auto-Sandbox settings: option Additional Protection/AutoSandbox and then click on Settings button.

Monolix initialization failure under Linux OS
If you are not able to run Monolix, a possible error can come from the existence of $HOME/.matlab directory with bad R/W right. In this case you can suppress the directory and re-run Monolix initialization by typing

#> ./monolix.sh --init.
Suggest Edit
Jonathan CHAUVINMonolixSuite2016R1 installation and administration guide