PineAPPL
and its interface is written in Rust,
but besides Rust PineAPPL also offers interfaces for the most popular
programming languages: C, C++ and Fortran via the C API and Python through
PyO3.
Furthermore the program pineappl
can be installed that will allow you to
perform many operations on grids in your favorite shell: the command-line
interface (CLI).
Pick the interface(s) you're planning to use and follow the corresponding instructions below. If you don't know which interfaces you'll likely use, here are a few guidelines:
- if you're planning to use PineAPPL with Python and/or within the NNPDF fitting framework, you'll need the Python interface;
- if you want to run a Monte Carlo to generate PineAPPL grids, you'll likely need the CAPI;
- if you want to quickly produce predictions, plots and small analyses install the CLI.
You can install the CAPI in two different ways:
- using pre-built libraries, which doesn't require installing any other dependencies, or
- alternatively you can build it from source, but this requires Rust and Cargo.
The fastest way to install the CAPI is to download the pre-built libraries:
curl --proto '=https' --tlsv1.2 -sSf https://nnpdf.github.io/pineappl/install-capi.sh | sh
The installation script will prompt you for the installation directory where the files shall be installed to. If you want to pass this directory on the command line, change the arguments to the shell:
.. | sh -s -- --prefix /my/custom/installation/path
By default install-capi.sh
will download the latest stable release. If you'd
like a specific version, pass the version along with --version
:
.. | sh -s -- --version 0.6.0-alpha.18
After the installation the script will check whether certain environment variables are set correctly and will complain if this is not the case. Read and follow the instructions of the script.
If you want to build the CAPI from its sources instead, you first need to
-
Install Rust, see the instructions below.
-
Then install
cargo-c
, which is required for the next step:cargo install cargo-c
It is possible that the installation fails if your Rust compiler is too old. In that case update Rust or try installing an older version of
cargo-c
:cargo install cargo-c --version 0.9.14+cargo-0.67
-
Next, check out PineAPPL's repository, for instance with
git clone https://github.com/NNPDF/pineappl.git cd pineappl
-
Now install
pineappl_capi
, PineAPPL's C API:cd pineappl_capi cargo cinstall --release --prefix=${prefix} --libdir=lib cd ..
where
${prefix}
points to the desired installation directory. -
Finally, if you installed the library into a non-standard prefix you need to set the environment variables
PKG_CONFIG_PATH
andLD_LIBRARY_PATH
to the right directories. Addingexport LD_LIBRARY_PATH=${prefix}/lib:$LD_LIBRARY_PATH export PKG_CONFIG_PATH=${prefix}/lib/pkgconfig:$PKG_CONFIG_PATH
to your
~/.bashrc
should do the trick (remember to replace${prefix}
with the correct directory). You can checkPKG_CONFIG_PATH
by runningpkg-config pineappl_capi --libs
which should print the library flags needed to link against the C API. If there's no output or an error, double-check that
PKG_CONFIG_PATH
is in the environment and that it points to a directory containing thepineappl_capi.pc
file.
If you want to update the CAPI, first update the PineAPPL repository with git pull
and then repeat step 3.
You can install the CLI in two different ways:
- using pre-built binaries, which doesn't require installing any other dependencies, or
- alternatively you can build it from source, but this requires Rust and Cargo.
The fastest way to install the CLI is to download the pre-built binaries, for
instance using pip
:
pip install pineappl-cli
or using the installation script:
curl --proto '=https' --tlsv1.2 -sSf https://nnpdf.github.io/pineappl/install-cli.sh | sh
The installation script will prompt you for the installation directory where the files shall be installed to. If you want to pass this directory on the command line, change the arguments to the shell:
.. | sh -s -- --prefix /my/custom/installation/path
By default install-cli.sh
will download the latest stable release. If you'd
like a specific version, pass the version along with --version
:
.. | sh -s -- --version 0.6.0-alpha.18
After the installation the script will check whether certain environment variables are set correctly and will complain if this is not the case. Read and follow the instructions of the script.
You need to install Rust first (see below). Then simply run
cargo install --locked pineappl_cli
anywhere and you are done; this will automatically download the most-recently released version from crates.io.
More functionality can be added by appending the --feature=feature1,...
flag,
see below.
To update the CLI simply repeat the cargo install
step; if a newer version is
available it will be automatically downloaded, otherwise cargo
will exit with
a message saying that the most recent version is already installed.
If you'd like to convert APPLgrids to PineAPPL grids, or vice versa, make sure to
-
install APPLgrid (you need at least version 1.6.27),
-
set the environment variable
APPL_IGRID_DIR
to thesrc
directory of APPLgrid and -
add the switch
--features=applgrid
during the CLI's installation, for instance:APPL_IGRID_DIR=/tmp/applgrid-1.6.27/src cargo install --locked --features=applgrid pineappl_cli
If you'd like to convert PineAPPL grids into FK tables using evolution kernel
operators (EKO), add the switch
--features=evolve
during the CLI's installation, for instance:
cargo install --locked --features=evolve pineappl_cli
If you'd like to convert fastNLO tables to PineAPPL grids, make sure to install
fastNLO first and add the switch
--features=fastnlo
during the CLI's installation, for instance:
cargo install --locked --features=fastnlo pineappl_cli
If you'd like to convert NNPDF's legacy FK tables to PineAPPL grids, add the switch
--features=fktable
during the CLI's installation, for instance:
cargo install --locked --features=fktable pineappl_cli
To use the most recent version available run
cargo install --locked --git https://github.com/NNPDF/pineappl.git pineappl_cli
Instead, if you plan to make changes to the source code it's better to checkout this repository and run
cargo install --locked --path pineappl_cli
inside it.
Most of PineAPPL's help is available as pineappl --help
and as pineappl convolve --help
, for example. However, the same information can also be
installed as man pages, which can then be used as either
man pineappl
man pineappl-convolve
or
pineappl help
pineappl help convolve
For this to work first install the CLI. Next, go to your local copy of PineAPPL's repository and create the man page directory relative to the CLI,
mkdir -p $(dirname $(which pineappl))/../share/man/man1/
and finally install the manpages there:
cargo xtask install-manpages $(dirname $(which pineappl))/../share/man/man1/
To install the Python interface, run
pip install pineappl
This will not require any previous installation of Rust. For more documentation and more information see its README.
You will need the Rust compiler and its build system cargo
. If cargo
is
already installed, make sure it is recent enough:
cargo --version
This should show a version that is at least 1.80.1. If you do not have cargo
or if it is too old, go to https://www.rust-lang.org/tools/install and follow
the instructions there.
The Rust crate is called pineappl.