Skip to content

mrgsolve Installation

Jump to bottom
Kyle Baron edited this page May 24, 2016 · 41 revisions

Prerequisites

  • R: https://cran.r-project.org/
    • Currently R >= 3.1.2 is required
  • Seriously consider running in Rstudio if possible. This is not required but is recommended.
  • Compilers: C++ and gfortran (see the Compilers section below)

Compilers

Current versions of C++ and FORTRAN compilers are required to use mrgsolve. Available compilers and requirements may vary by operating system. Please see system-specific instructions below. But note well that the toolchain that needs to be in place is the usual toolchain required for ordinary use of R (either to compile R from source or to compile R packages from source). There is very detailed and complete information on compilers to use with R on the r-project website (https://cran.r-project.org/doc/manuals/R-admin.html and see links below). There are no special compiler requirements to get mrgsolve up and running; just install the compilers you would normally need to use with R and mrgsolve will compile and you will be able to compile your mrgsolve models.

The compilers will be used to compile C++ and FORTRAN code inside the mrgsolve package as well as user-created models. It is imperative that mrgsolve be compiled with the same compiler used to compile the user-created model. If different compilers are used, it is likely that a segmentation fault will happen. This behavior would be expected when different compilers are used.

Windows users

You need to download and properly install the Windows toolset (Rtools). Do not use any compiler other than the one provided by the r-project. You MUST use Rtools. Please update to a recent version even if you think you already have it installed.

Installation instructions and download links for Rtools can be found in these links:

Please read carefully. There isn't a lot to read here, but there are clear and easy-to-follow directions about what you need to do directly from the R people.

Tips for installing the Rtools toolchain

These tips are based on many hours spent helping people install Rtools for Windows properly.

  • Read about the Windows toolset
    • Especially if things are not working for you, there is important information to be found in this link. If you haven't read this, read it now.
  • Download RtoolsXX.exe
    • XX is the version number (e.g. Rtools32.exe)
    • Get the version number that corresponds to your version of R
    • Do not get a version that is not frozen yet; experience has told us that the latest / newest version isn't at all the best
  • Install RtoolsXX.exe
    • When you are installing, pay attention for a prompt asking about changing the PATH; make sure that the installer updates PATH
  • Check your PATH environment variable in R
    • Use the command Sys.getenv("PATH") in R, after restarting to make sure the proper directories are listed there. R will not find the toolchain unless the PATH is correctly
    • If PATH is not properly set, try to set it with a system-wide environment variable
    • If a system-wide environment variable is not posible, there are some other options here
  • Install Rcpp, RcppArmadillo, and mrgsolve all from source
    • Do this even if you think you already have them installed; it is important to re-install these packages after installing Rtools
    • To install from source: install.packages(c("Rcpp", "RcppArmadillo"), type="source")
  • Common error messages from incorrect Windows installs can be found here

See also

Mac OSX users

If using R binary from CRAN

A suitable C++ compiler is available in Xcode (https://developer.apple.com/xcode/). Be sure to download and install command line tools (bash$ xcode-select --install). Always use the most up to date version.

Xcode does not include a FORTRAN compiler. There are different FORTRAN compiler requirements for Snow Leopard or Mavericks (or greater) R builds. See the platform-specific FAQs below.

Carefully read the following for information:

  1. https://cran.r-project.org/doc/manuals/R-admin.html#OS-X
  2. https://cran.r-project.org/doc/manuals/R-admin.html#Mavericks-and-later

To get gfortran for Mac OSX specificially, first please note if you are using a Mavericks build or Snow Leopard build (your choice of gfortran compiler will depend on this).

  1. gfortran for Mavericks build:

  2. gfortran for Snow Leopard build:

If using R installed from homebrew

  • We recommend and support using the CRAN binary and toolchain, but we understand that a pure homebrew implementation (R and toolchain) has worked.
    • The key seems to be matching the homebrew R install with the homebrew gcc install.
  • If you are using the homebrew approach, please contact personnel from that project for help with compiler issues.

Unix users

UNIX usually include C++ and FORTRAN compliers. If not, install gcc.

Obtaining mrgsolve

  • Get the latest release here
  • Get the development version with the devtools package:
library(devtools)
devtools::install_github("metrumresearchgroup/mrgsolve", subdir="rdev", type="source")

Dependencies

Installing mrgsolve via install_github will also install required dependencies. It is best practice to use the most recent version of mrgsolve and recent versions of all depencencies. The following section will discuss what depencencies are required.

Installing packages in R

See https://cran.r-project.org/web/packages/ or R> help("INSTALL") or R> help("install.packages") for help.

Required packages

The following required packages must be installed before installing mrgsolve:

  1. BH
  2. Rcpp
  3. RcppArmadillo
  4. dplyr

All of these required packages are available on CRAN. mrgsolve imports from dplyr and links to BH, Rcpp, and RcppArmadillo. For the purposes of this document, they will be referred to as dependencies insofar as they are required to install and run mrgsolve. But note well that they are not technically dependencies the way R uses that term. Only the package namespaces and not the packages themselves will be loaded when mrgsolve is loaded.

There are minimum version numbers for each dependency. R will issue an error during mrgsolve installation if insufficient versions of dependencies are currently installed. See the DESCRIPTION file in the .tar.gz archive for minimum dependency version numbers. Also, note that each required package with respect to mrgsolve may have requirements of their own. Install all required packages and their requirements as well prior to installing mrgsolve.

NOTE: Rcpp and RcppArmadillo must be installed from source packages (e.g. install.packages("Rcpp", type="source")). Also, whenever new versions of Rcpp, RcppArmadillo or mrgsolve are installed, it is good practice to re-install / re-compile all three of these packages (see Compilers below).

Suggested packages

These packages may be needed to perform certain tasks in mrgsolve:

  1. lattice
  2. testthat
  3. XML

R users usually already have lattice installed on their system. testthat and XML are only required for a few tasks and the majority of the simulation work can be done without them.

Example installation code

Setup

Point the installation to your favorite CRAN repository:

repos <- "http://cran.us.r-project.org"

Install dependencies

This little function will ensure that source packages are installed from CRAN; do NOT install binary packages.

install <- function(x,...) install.packages(x,type="source",repos=repos,...)

Install dependencies:

install("Rcpp")
install("RcppArmadillo")
install("BH")
install("dplyr")

Install mrgsolve

To install version 0.6.1 from the source tarball:

Check that you can find the tarball. For example:

file.exists("mrgsolve_0.6.1.tar.gz")

Use the name of the tarball that you downloaded and the path to that file. If this doesn't come back TRUE, modify the command (file name or path) untill R can find it.

Install:

install.packages("mrgsolve_0.6.1.tar.gz", repos=NULL, type="source")

Note that repos is set to NULL and we are telling R that the package is source, not binary. Also, we assume that the mrgsolve_0.6.1.tar.gz file is in the current working directory (see previous check).

To install other versions of mrgsolve, use the appropriate version number in for the tarball that you are trying to install (e.g. mrgsolve_a.b.xyz.tar.gz).

Alternative: install via devtools

mrgsolve and all depencencies can be installed with this command

library(devtools)
install_github("metrumresearchgroup/mrgsolve@v0.6.1", subdir="rdev", type="source")

Test the installation

library(mrgsolve)
?mrgsolve
example("mrgsolve")

Upgrading to a new version

Users are encouraged to re-install or re-compile Rcpp and RcppArmadillo prior to upgrading to a new version of mrgsolve. To upgrade mrgsolve, simply follow the install step above.

© 2016 Metrum Research Group, LLC
www.metrumrg.com
Clone this wiki locally