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 all 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.

2. Installation Location and Package Contents

Common installation locations:

  • Linux/macOS: ~/perplex/

  • Windows: C:\perplex

After unpacking, the directory structure should be:

perplex/
    binary/          — Perple_X executables (build, vertex, pssect, etc.)
    datafiles/       — Thermodynamic data and solution model files
    optionfiles/     — Option files read by Perple_X programs
    matlab_scripts/  — Perple_X MATLAB utilities (see Section 5)

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 binary to your PATH (Section 4), copy the executables into your working directory.

3. Using a Command Shell

Warning

Perple_X programs must be run from a command shell. Running them by clicking icons hides diagnostic messages if something goes wrong. To run Perple_X programs from a command shell: open the shell, change to your working directory, and, after setting PATH (Section 4), enter the program name (Section 7).

—

Windows: PowerShell or Command Prompt

Open PowerShell:

  • Win+R → powershell → Enter

Open Command Prompt:

  • 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 Your PATH

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

—

Windows

System Properties → Environment Variables → Path → Add:

C:\perplex\binary

—

Linux

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

—

macOS

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

Warning

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.

Tip

Use the scripts when MATLAB is available; the compiled applications are slower and less flexible.

—

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 use the scripts: set your MATLAB working directory to matlab_scripts/ or simply copy the scripts to your working directory.

—

The standalone compiled MATLAB applications are only available for Windows and are in MATLAB_WIN_programs_R2024b.zip. The compiled 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

—

GSview for Viewing *.ps Files

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

7. Test Your Installation

  • 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 GSview or another PostScript viewer. The result should be comparable to https://www.perplex.ethz.ch/perplex/examples/jn7.pdf

8. Additional Resources