Installing Perple_X from GitHub Releases

This document explains how to install and configure Perple_X using the releases at GitHub. Each release provides platform-specific executables, required data and option files, and MATLAB-based helper utilities.

Note

To install Perple_X directly from the Perple_X web site refer to the legacy instructions. New users should install Perple_X using the GitHub release packages described here.

1. Obtain the Perple_X Release Package

Navigate to https://github.com/jadconnolly/Perple_X/releases/

Note

Click Assets beneath the release description to reveal downloadable packages.

Each package is named using the release tag, for example:

  • Perple_X_v7.1.15_Linux_64_gfortran.tar.gz

  • Perple_X_v7.1.15_macOS_64_gfortran.tar.gz

  • Perple_X_v7.1.15_Windows_64_gfortran.zip

Download the package corresponding to your operating system.

Runtime library compatibility

Release 7.1.18+ executables should run out-of-the-box:

  • Windows executables are self-contained.

  • Linux and macOS executables are built to minimize external requirements. Should problems arise refer to executable issues.

Note

For maximum control and optimization compile from source.

2. Installation Location and Package Contents

Common installation locations:

  • Linux/macOS: ~/perplex/

  • Windows: C:\perplex

After unpacking, the directory structure is:

perplex/
    bin/             — Perple_X executables (build, vertex, pssect, etc.)
    datafiles/       — Thermodynamic data and solution model files
    lib/             — bundled libraries (macOS only)
    optionfiles/     — Option files read by Perple_X programs
    matlab_scripts/  — Perple_X MATLAB utilities (see Section 5)
    src/             — Perple_X source code (not needed for installation)

Note

  • Although you can include path information in Perple_X file names, it is recommended that you copy the data and option files necessary for your project into your working directory (e.g., perplex/my_project/).

  • If you don’t want to add bin to your PATH (Adding to PATH), copy the executables into your working directory.

macOS Library Location

if the executables are moved from bin/, the lib/ directory must be moved along with them to ensure that the bundled libraries are found at runtime.

3. Using a Command Shell

Perple_X programs must be run from a command shell

Running them by clicking icons hides diagnostic messages if something goes wrong. To run the programs: open a shell as described below, change to your working directory, and, after setting PATH (Adding to PATH), enter the program name (Testing).

—

Windows: powershell or cmd

  • Win+R → powershell → Enter

  • Win+R → cmd → Enter

Tip

Either shell can be customized so that it starts in your Perple_X working directory.

—

Linux: Terminal, Bash, or Zsh

Open a terminal:

  • Ctrl+Alt+T on most systems

  • or open Terminal from the desktop environment

Check shell:

echo $SHELL

Customize:

  • Bash: ~/.bashrc

  • Zsh: ~/.zshrc

Reload:

source ~/.bashrc

—

macOS: Terminal.app or Zsh

Open Terminal:

  • Applications → Utilities → Terminal

  • Cmd+Space → Terminal

Check shell:

echo $SHELL

Customize:

  • ~/.zprofile for PATH

  • ~/.zshrc for interactive settings

Reload:

source ~/.zprofile

4. Add Perple_X to PATH

Adding bin to PATH allows you to run Perple_X from any directory.

—

Windows

System Properties → Environment Variables → Path → Add:

C:\perplex\bin

—

Linux

export PERPLEX_HOME="$HOME/perplex"
export PATH="$PERPLEX_HOME/bin:$PATH"

—

macOS

export PERPLEX_HOME="$HOME/perplex"
export PATH="$PERPLEX_HOME/bin:$PATH"

Remove quarantine if needed

xattr -dr com.apple.quarantine $PERPLEX_HOME

5. MATLAB Utilities

The matlab_scripts/ directory contains MATLAB scripts and standalone compiled MATLAB applications. These utilities are useful for plotting 2- and 3-d *.tab files generated by werami, fluids, frendly, and vertex, and for visualizing and analyzing *.pts files generated by MC_fit.

Use the scripts when MATLAB is available

The compiled applications are slower and less flexible.

—

MATLAB Scripts

The MATLAB scripts (*.m) are:

  • perplex_plot.m — plots 2-D and 3-D *.tab files

  • perplex_simple_plot.m — plots 2-D and 3-D *.tab files with default independent variables

  • MC_fit_plot.m — MC_fit visualization and analysis

  • perple_x_plot_ratio_of_data_in_2_files.m — plots the ratio of 3D data stored in two different files.

  • perple_x_extract_o_bat.m — extracts the X-Y coordinates of an X-Y-Z contour, e.g., an adiabatic or isochoric path as a function of pressure and temperature.

  • function_*.m — functions used by the above scripts.

To make MATLAB find the scripts automatically

Create a startup.m file to add matlab_scripts/ to the MATLAB search path.

First, find your user startup location:

userpath

Then create (or edit) a file named startup.m in that folder and add your path commands, for example:

% startup.m — run automatically at MATLAB launch
addpath(genpath('C:\perplex\matlab_scripts'));

Run startup or restart MATLAB for the changes to take effect.

This approach avoids permission issues associated with savepath, because startup.m resides in your user directory.

—

Compiled MATLAB Applications

The standalone compiled MATLAB applications are only available for Windows and are in MATLAB_WIN_programs_R2024b.zip. The applications have the same names and functionality as the corresponding MATLAB scripts.

To use the applications:

  • Unpack the ZIP archive to a convenient location (e.g., C:\Perple_X\matlab_scripts).

  • Install the free MATLAB Runtime (MCR) corresponding to the operating system (WIN) and MATLAB release (R2024b) used to compile the applications: https://www.mathworks.com/products/compiler/matlab-runtime.html

  • Run the applications from a console or terminal window as done for other Perple_X programs.

6. External Helper Utilities

—

PyWerami for Plotting *.tab Files

PyWerami is a free, Python-based, alternative to MATLAB for viewing 2- and 3-D *.tab file output from the Perple_X programs werami, fluids, frendly, and vertex. It is vastly superior to the Perple_X pstab program: https://anaconda.org/channels/ondrolexa/packages/pywerami/overview

—

Ghostview for Viewing *.ps Files

Perple_X programs generate PostScript (*.ps) files. Ghostview is a free, efficient, PostScript viewer: https://github.com/ArtifexSoftware/ghostpdl-downloads

7. Testing

  • Open a command shell (powershell, Terminal, etc.).

  • Change to your Perple_X working directory:

    cd C:\perplex

  • Download the problem definition file jn7.dat from https://www.perplex.ethz.ch/perplex/examples/jn7.dat to your working directory.

  • Copy the thermodynamic data file sup92ver.dat from datafiles/ to your working directory:

    cp datafiles\sup92ver.dat .

  • Run vertex, answer y to any prompts about continuing execution after a warning.

    vertex
...
Enter the project name (the name assigned in BUILD) [default = my_project]:
jn7
...
Continue execution despite this warning (Y/N)?
y
...
--------------------------------------------------------------------------------
End of job: jn7
--------------------------------------------------------------------------------

  • Run pssect to generate the phase diagram section PostScript file jn7.ps:

    pssect
...
Enter the project name (the name assigned in BUILD) [default = my_project]:
jn7

PostScript will be written to file: jn7.ps

Modify the default plot (y/n)?
n

  • View jn7.ps with Ghostview or another PostScript viewer. The result should be comparable to https://www.perplex.ethz.ch/perplex/examples/jn7.pdf

8. Additional Resources