alphaMELTS installation and testing - magmasource/alphaMELTS GitHub Wiki

alphaMELTS (standalone app)

GENERAL INFORMATION

It is helpful to have easyMelts installed for the same version i.e. Mac, Linux, or native Windows, as it can be used to create .melts input files that also work in alphaMELTS (and should have the correct line endings). On Mac we try to support the three most recent macOS versions. On Windows we try to support Windows 10 and 11. On Linux we try to support the version of Ubuntu used by Google Colab and/or the Windows Subsystem for Linux (Ubuntu 22.04 LTS at the time of writing).

Installing on macOS

SYSTEM REQUIREMENTS

As of writing, the only requirement is that macOS is updated to Monterey or later. alphaMELTS works best with Perl installed, and the install script uses it, but Perl is installed by default on macOS. It is easiest to run scripts like install.command and run-alphamelts.command from the Terminal command line app (which can be found in '/Applications/Utilities') but double-clicking is also possible.

INSTALLING and UPDATING (macOS)

Go to Releases, download and expand the appropriate .zip file. This is the equivalent of the 'package' folder that was previously available in the alphaMELTS2 repository on GitLab and the MAGMA Source GitList server.

Install the alphaMELTS package by double-clicking 'install.command', or use cd to navigate to the 'alphaMELTS2/package' folder (or whatever it is called on your system) in Terminal and type ./install.command. It is easiest to take the default settings. This will make the links_folder either '∼/bin' if the folder exists due to a previous alphaMELTS installation or in '∼/Documents/bin', which is a bit easier to locate in Finder ('∼' is the user's home space).

The 'install.command' script may print a message that you need to set the Path variable, together with brief operating-system-specific instructions on how to do this. Please do not skip this step! Most reported problems in running alphaMELTS are because the user has not set the Path. Note that it is the links_folder (likely to be '∼/bin' or '∼/Documents/bin') that needs to be added to the Path, not the downloaded folder.

If you install something like Anaconda after installing alphaMELTS it can break the alphaMELTS installation. Simply run install.command again to repair it. Likewise, if you move the download_folder you will need to rerun install.command.

To update alphaMELTS when there is a newer version, simply download and replace the run-alphamelts.command script and alphamelts executable. Alternatively, replace the whole folder and rerun install.command.

RUNNING alphaMELTS (macOS)

The easiest way to use alphaMELTS is to open Terminal, navigate to where your input files are with cd and then type run-alphamelts.command, with or without command line switches. Note that there is no ./ at the start of this command. Alternatively, you can double-click the run-alphamelts.command file, but you need to make sure to click the script in the links_folder (likely to be '∼/bin' or '∼/Documents/bin') and not the one in the folder that you downloaded.

The first time you try to run alphaMELTS it may fail due to Mac security settings. If you see options like Move to Trash and Cancel then click Cancel. Go to System Preferences → Security & Privacy (depending on your macOS version you may need to select the General tab) Select Allow anyway, and then try again. The second time you will be asked whether to Open or not (either Move to Trash or Cancel), so pick Open.

Test your installation by typing run-alphamelts.command -h for an explanatory list of command line switches. Then run the tutorial using the files in the examples directory. Note that the files have Windows line endings. You can set them to macOS line endings by typing file-format.command More.melts (substitute 'More.melts' for the other file names, as needed).

Installing on Windows

SYSTEM REQUIREMENTS

The Windows Subsystem for Linux is a good option for the standalone alphaMELTS app on Windows 10 and 11, as the Linux installation includes Perl etc. and setting the Path variable is easier. WSL does require admin access for initial set up but not for updating alphaMELTS. In that case follow the Installing on Linux part of the guide. Otherwise follow this guide for running natively on Windows.

It is possible to run the alphamelts_win64.exe file as is, but having Perl installed unlocks many useful features for automating calculations and manipulating output. MATLAB contains a small Perl installation, or Perl can easily be installed via Anaconda. Otherwise, for users without admin access we recommend the portable version of Strawberry Perl; simply unzip the file and, optionally, move the folder to a more convenient location on your hard disk (the alphaMELTS 'install.command' script will do the required set up later.

It is recommended to install the Windows Terminal. Search for 'Windows Terminal' in the Microsoft Store. Selecting 'Command Prompt' from the drop down menu (the 'V' button) is the best way to run scripts like 'run-alphamelts.command'.

INSTALLING and UPDATING (Windows)

To install the alphaMELTS package: right-click 'install2.command' to choose 'Open with...' and browse to the 'perl.exe' executable (e.g. strawberry_perl_folder\perl\bin\perl.exe, or 'C:\Program Files\MATLAB\Rrelease\sys\perl\win32\bin\perl.exe’, or 'C:\Users\username\Anaconda3\Library\bin\perl.exe’). . It is easiest to take the default settings. This will make the links_folder in '%USERPROFILE%\Documents\bin'.

The 'install.command' script may print a message that you need to set the path variable, together with brief operating-system-specific instructions on how to do this. Please do not skip this step! Most reported problems in running alphaMELTS are because the user has not set the path. Note that it is the links_folder (likely to be '%USERPROFILE%\Documents\bin') that needs to be added to the Path, not the downloaded folder.

Open the Settings app and type 'env' in the search bar, located at the top in Windows 10 and to the left in Windows 11. Select 'Edit environment variables for your account'.
Select 'Path' then 'Edit...' from the upper box, which should be labeled 'User variables for your_user_name'. A new 'Edit environment variable' window should open. Select 'New' and then 'Browse...' to select the links_folder.
If there is no 'Path' variable for the your_user_name account then select 'New...' instead. Put 'Path' for the Variable name (without the quotes) and 'Browse Directory...' to set the Variable value to the links_folder.

Warning: do not edit or delete the existing folders in the user's Path or you may break existing software installations. And please do not edit the System PATH variable.

When a new release becomes available, simply download the new package and replace the old files.

RUNNING alphaMELTS (Windows)

The easiest way to use alphaMELTS is to open a terminal command line e.g. the 'Command Prompt' in the Windows Terminal. Navigate to where your input files are with cd and then type run-alphamelts.command, with or without command line switches. Alternatively, you double-clicking the run-alphamelts.command file works well on Windows, but you need to make sure to click the script in the links_folder (likely to be '%USERPROFILE%\Documents\bin') and not the one in the folder that you downloaded.

Installing on Linux

SYSTEM REQUIREMENTS

As of writing, the only requirement is that the version of the Gnu Science Library installed by the system is 2.7, which includes Ubuntu 22.04 LTS and later. alphaMELTS works best with Perl installed, and the install script uses it, but Perl is installed by default on almost all Linux systems. It is easiest to run scripts like install.command and run-alphamelts.command from the a terminal command line but double-clicking is also possible sometimes.

INSTALLING and UPDATING (Linux)

Go to Releases, download and expand the appropriate .zip file. This is the equivalent of the 'package' folder that was available on GitLab and the MAGMA Source GitList server previously.

Install the alphaMELTS package by double-clicking 'install.command', or use cd to navigate to the 'alphaMELTS2/package' folder (or whatever it is called on your system) in a terminal command line and type ./install.command. For the WSL you will need to open Ubuntu, se cd to navigate to the 'alphaMELTS2/package' folder (or whatever it is called on your system) in a terminal command line and type ./install.command. It is easiest to take the default settings. This will make the links_folder either '∼/bin' if the folder exists due to a previous alphaMELTS installation or in '∼/Documents/bin', which is a bit easier to locate in a file manager ('∼' is the user's home space).

The 'install.command' script may print a message that you need to set the Path variable, together with brief operating-system-specific instructions on how to do this. Please do not skip this step! Most reported problems in running alphaMELTS are because the user has not set the Path. Note that it is the links_folder (likely to be '∼/bin') that needs to be added to the Path, not the downloaded folder.

RUNNING alphaMELTS for MATLAB (Linux)

The easiest way to use alphaMELTS is to open a terminal command line, navigate to where your input files are with cd and then type run-alphamelts.command, with or without command line switches. Note that there is no ./ at the start of this command. Alternatively, you double-clicking the run-alphamelts.command file works on some Linux systems, but you need to make sure to click the script in the links_folder (likely to be '∼/bin') and not the one in the folder that you downloaded.

Test your installation by typing run-alphamelts.command -h for an explanatory list of command line switches. Then run the tutorial using the files in the examples directory. Note that the files have Windows line endings. You can set them to Linux line endings by typing file-format.command More.melts (substitute 'More.melts' for the other file names, as needed).

alphaMELTS for MATLAB

GENERAL INFORMATION

alphaMELTS for MATLAB is currently developed using R2023b for Apple Silicon and R2021b for other platforms but older and newer versions should work also. It is helpful to have the standalone alphaMELTS app (and easyMelts) installed for the same version i.e. Mac, Linux, or native Windows. On Mac we try to support the three most recent macOS versions. On Windows we try to support Windows 10 and 11. On Linux we try to support the version of Ubuntu used by Google Colab and/or the Windows Subsystem for Linux (Ubuntu 22.04 LTS at the time of writing).

Documentation strings within the MELTS...m files have been thoroughly populated for MELTSdynamic and MELTSengine but less so for the other files. You can see brief information on the structure of the MELTS for MATLAB classes by typing something like help MELTSdynamic (with or without the '.m') or help MELTSengine and then clicking the 'Reference page for ...' links.

Installing on macOS

SYSTEM REQUIREMENTS

alphaMELTS for MATLAB requires a C compiler be installed. If you have Xcode installed, and it is up to date, this will work. If you do not have Xcode you do not need to install it, and you probably don't want to as it is huge(∼10 GB)! Instead install just the Command Line Tools, which are < 1 GB; you will get some warnings when you run alphaMELTS for MATLAB, but they are harmless and can be suppressed. To install see Install Xcode Command Line Tools and then see Mex on macOS without Xcode to tell MATLAB that you agreed to the Xcode license; finally, the next time you open MATLAB, type mex -setup C. You need only do these steps once (unless you upgrade macOS or move to a new MATLAB release).

alphaMELTS for MATLAB also uses the GNU Science Library (GSL). For Mac the file is most easily installed via Homebrew: install Homebrew as directed on the homepage (or see below for M1/M2/M3 chip Macs) and then type brew install gsl at the Terminal command line. It can also be downloaded directly but this has not been tested with alphaMELTS for MATLAB.

On Apple Silicon, the default install command will install Homebrew to /opt/Homebrew. This will work if you have the native version Apple Silicon version of MATLAB, which has been available since R2023b:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

If you have an older version of MATLAB then you need to install the Intel version of Homebrew / GSL using this command:

arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Enter your normal user password if asked. This second command will put the files in /usr/local. Finally type /usr/local/Homebrew/bin/brew install gsl. You can have both versions of Homebrew installed on the same machine.

INSTALLING and UPDATING

Go to Releases, download and expand the appropriate .zip file. This is the equivalent of the 'package' folder that was previously available in the MELTS_Matlab repository on GitLab and the MAGMA Source GitList server.

The first time you try to run alphaMELTS for MATLAB it may fail due to Mac security settings. If you see options like Move to Trash and Cancel then click Cancel. Go to System Preferences → Security & Privacy (depending on your macOS version you may need to select the General tab) Select Allow anyway, and then try again. The second time you will be asked whether to Open or not (either Move to Trash or Cancel), so pick Open.

When a new release becomes available, make sure to update Homebrew (brew update, then brew upgrade). Then simply download the new package and replace the old files. You will need to bypass the security settings again.

RUNNING alphaMELTS for MATLAB (macOS)

On Mac, you need to open MATLAB from the command line so that messages from the MELTS library are directed to the terminal command line. You can type something like /Applications/MATLAB_R2023b.app/bin/matlab & (substitute the MATLAB release that you have, if appropriate) or you can set up an alias so that you don't need to type the whole line each time.

You need to make sure the 'MELTS_Matlab/package' folder (or whatever the folder is called on your system) is in the MATLAB path. There are various ways to do this, including right clicking on the folder and selecting 'Add to Path'. Alterntively, type addpath('PATH_TO_THE_MELTS_MATLAB_PACKAGE_FOLDER') substituting the correct path.

Test your installation by running the tutorial.m file in the examples directory.

Installing on Windows

SYSTEM REQUIREMENTS

It is possible to install the Linux version of MATLAB in the Windows Subsystem for Linux, in which case follow the Installing on Linux part of the guide. Otherwise follow this guide for running natively on Windows.

alphaMELTS for MATLAB requires a C compiler be installed. On Windows, MATLAB will offer to install MinGW as a MATLAB add-in if it can't find a compiler; you will need to log in with your Mathworks account. Or go here to install the add-in directly. Alternatively, or as well, you can use Visual Studio. Visual Studio has a Community Edition that is free for academia, though alphaMELTS for MATLAB has not been tested on the latest version (2022). There is also standalone MinGW-w64, which is available as part of the MSYS2 toolchain or as part of Rtools.

alphaMELTS for MATLAB also uses the GNU Science Library (GSL). For Windows, this and other .dll pre-requsites are provided.

INSTALLING and UPDATING

When a new release becomes available, simply download the new package and replace the old files.

RUNNING alphaMELTS for MATLAB (Windows)

On Windows, just open MATLAB in the normal way; a console for MELTS library messages has been added as part of the alphaMELTS for MATLAB package.

On native Windows the user's 'PATH' or 'Path' variable may also need to include 'MELTS_Matlab\package' (or whatever the folder is called), as that is where it will search for the C dynamic library of MELTS functions. This seems to vary with specific Windows updates and MATLAB version so we recommend you try running alphaMELTS for MATLAB first and only set the Path if needed. If you are sure that 'PATH_TO_THE_MELTS_MATLAB_PACKAGE_FOLDER' has been added to the MATLAB path but are getting library not found type errors then try:

Open the Settings app and type 'env' in the search bar, located at the top in Windows 10 and to the left in Windows 11. Select 'Edit environment variables for your account'.
Select 'Path' then 'Edit...' from the upper box, which should be labeled 'User variables for your_user_name'. A new 'Edit environment variable' window should open. Select 'New' and then 'Browse...' to select the 'PATH_TO_THE_MELTS_MATLAB_PACKAGE_FOLDER'.
If there is no 'Path' variable for the your_user_name account then select 'New...' instead. Put 'Path' for the Variable name (without the quotes) and 'Browse Directory...' to set the Variable value to the 'PATH_TO_THE_MELTS_MATLAB_PACKAGE_FOLDER'.

Warning: do not edit or delete the existing folders in the user's Path or you may break existing software installations. And please do not edit the System PATH variable.

Test your installation by running the tutorial.m file in the examples directory.

Installing on Linux

SYSTEM REQUIREMENTS

alphaMELTS for MATLAB requires a C compiler be installed. Most laptop or desktop installations of Linux will include a compiler, but the WSL installation of Ubuntu does not by default. We recommend you install clang (sudo apt install clang) but gcc will work too.

alphaMELTS for MATLAB also uses the GNU Science Library (GSL). On Linux it can be installed via the package manager (e.g. apt install gsl-bin on Ubuntu). It can also be downloaded directly but this has not been tested with alphaMELTS for MATLAB.

INSTALLING and UPDATING

Go to Releases, download and expand the appropriate .zip file. This is the equivalent of the 'package' folder that was available on GitLab and the MAGMA Source GitList server previously.

When a new release becomes available, make sure GSL is up to date (sudo apt update, then sudo apt upgrade). Then simply download the new package and replace the old files.

RUNNING alphaMELTS for MATLAB (Linux)

On Linux, you need to open MATLAB from the command line so that messages from the MELTS library are directed to the terminal command line. You can type probably just type matlab &. On the Windows Subsystem for Linux (WSL) you may need to add a link to the executable cd /usr/local/bin; sudo ln -sf ../MATLAB/R2021b/bin/matlab (substitute the MATLAB release that you have, if appropriate).

Test your installation by running the tutorial.m file in the examples directory.

alphaMELTS for Python

GENERAL INFORMATION

alphaMELTS for Python is currently developed using Python 3.10, as that is the version used in Google Colab and ENKI's Thermoengine. Older and newer versions should work also. It is helpful to have the standalone alphaMELTS app (and easyMelts) installed for the same version i.e. Mac, Linux, or native Windows. On Mac we try to support the three most recent macOS versions. On Windows we try to support Windows 10 and 11. On Linux we try to support the version of Ubuntu used by Google Colab and/or the Windows Subsystem for Linux (Ubuntu 22.04 LTS at the time of writing).

Docstrings have been added for the meltsdynamic.py and meltsengine.py files but not other files (yet). You can see brief information on the methods in the MELTS for Python classes by typing something like help(MELTSdynamic) or help(MELTSengine). For information about class properties (e.g. units for thermodynamic quantities) you will need to examine the .py scripts.

Installing on macOS

SYSTEM REQUIREMENTS

alphaMELTS for Python requires a Python 3 environment and your choice of Python IDE (integrated development environment). Although alphaMELTS for Python can use the system python3 bundled with macOS or a python3 instance installed with Homebrew, it is recommended to create a separate Python environment. A quick Google search for 'python environments on Mac' brings up multiple guides that can help you pick the set up that suits your needs and level of experience. Visual Studio Code can be used to run Python scripts or Jupyter Notebooks and is the most thoroughly tested IDE for alphaMELTS for Python. There are other options, e.g. Anaconda python comes with Spyder and Jupyter, and RStudio can be used as an IDE for Python and R simultaneously.

alphaMELTS for Python requires a C compiler (or at least the C runtime libraries) be installed. If you have Xcode installed, and it is up to date, this will work. If you do not have Xcode you do not need to install it, and you probably don't want to as it is huge(∼10 GB)! Instead install just the Command Line Tools, which are < 1 GB; you will get some warnings when you run alphaMELTS for MATLAB, but they are harmless and can be suppressed. To install see Install Xcode Command Line Tools.

alphaMELTS for Python also uses the GNU Science Library (GSL). For Mac the file is most easily installed via Homebrew: install Homebrew as directed on the homepage (or see below for M1/M2/M3 chip Macs) and then type brew install gsl at the Terminal command line. It can also be downloaded directly but this has not been tested with alphaMELTS for Python.

On Apple Silicon, the default install command will install Homebrew to /opt/Homebrew. This should work unless you are using a version of Anaconda installed before they offered native Apple Silicon support:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

If you have an older version of Anaconda then you need to install the Intel version of Homebrew / GSL using this command:

arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

INSTALLING and UPDATING

The first time you try to run alphaMELTS for Python it may fail due to Mac security settings. If you see options like Move to Trash and Cancel then click Cancel. Go to System Preferences → Security & Privacy (depending on your macOS version you may need to select the General tab). Select Allow anyway, and then try again. The second time you will be asked whether to Open or not (either Move to Trash or Cancel), so pick Open.

RUNNING alphaMELTS for Python (macOS)

For now, until alphaMELTS for Python is properly packaged (e.g. so that it can be installed via pip or conda), you will need to set the PYTHONPATH environment variables to include the path to 'MELTS_Matlab/package', or whatever the folder is called on your system. There are various ways to do that. One way is to open Terminal and type export PATH=$PATH:PATH_TO_THE_MELTS_MATLAB_PACKAGE_FOLDER. Then open the IDE from the Terminal command line e.g. type code . to open VS Code.

Test your installation by running the tutorial.py file or tutorial.ipynb notebook in the examples directory.

Installing on Windows

SYSTEM REQUIREMENTS

One option is to run alphaMELTS for Python in the Windows Subsystem for Linux, in which case follow the Installing on Linux part of the guide. Otherwise follow this guide for running natively on Windows.

alphaMELTS for Python requires a Python 3 environment and your choice of Python IDE (integrated development environment). Beginners might want to install Python from the Windows Store; more experienced users will probably want to create a Python environment, either using pip or conda. A quick Google search for 'python environments on Windows' brings up multiple guides that can help you pick the set up that works for you. Anaconda python is a popular choice on Windows that comes with Spyder and Jupyter. Visual Studio Code can be used to run Python scripts or Jupyter Notebooks and is the most thoroughly tested IDE for alphaMELTS for Python, and RStudio can be used as an IDE for Python and R simultaneously.

alphaMELTS for Python requires a C compiler, or at least the C runtime libraries, be installed. On Windows, even if you have not installed a C compiler, it is likely that alphaMELTS for Python will still run because many applications (including most software by Microsoft and Adobe) install copies of the Microsoft Visual C++ Redistributable libraries. If not, and if you do not want to install the full Visual Studio Community Edition, you can get the relevant libraries here; scroll down to "Other Tools and Frameworks" at the bottom of the page. There is also the MinGW-w64 compiler, which is available as part of the MSYS2 toolchain or as part of Rtools.

alphaMELTS for Python also uses the GNU Science Library (GSL). For Windows, this and other .dll pre-requsites are provided.

INSTALLING and UPDATING

When a new release becomes available, simply download the new package and replace the old files.

RUNNING alphaMELTS for Python (Windows)

For now, until alphaMELTS for Python is properly packaged (e.g. so that it can be installed via pip or conda), you will need to set the PYTHONPATH environment variables to include the path to 'MELTS_Matlab/package', or whatever the folder is called on your system. There are various ways to do that, depending which IDE you are using. One way is to open a terminal program either (a) Windows PowerShell, and type $env:PYTHONPATH = "PATH_TO_THE_MELTS_MATLAB_PACKAGE_FOLDER", or (b) Windows Command Prompt, and type set PYTHONPATH = "PATH_TO_THE_MELTS_MATLAB_PACKAGE_FOLDER". Then open the IDE from the terminal command line e.g. type code . to open VS Code.

On native Windows the user's 'PATH' or 'Path' variable may also need to include 'MELTS_Matlab\package' (or whatever the folder is called), as that is where it will search for the C dynamic library of MELTS functions. This seems to vary with specific Windows updates and Python / IDE versions so we recommend you try running alphaMELTS for Python first and only set the Path variable if needed. If you are sure that PATH_TO_THE_MELTS_MATLAB_PACKAGE_FOLDER has been added to the PYTHONPATH but are getting library not found type errors then try:

Open the Settings app and type 'env' in the search bar, located at the top in Windows 10 and to the left in Windows 11. Select 'Edit environment variables for your account'.
Select 'Path' then Edit... from the upper box, which should be labeled 'User variables for your_user_name'. A new 'Edit environment variable' window should open. Select New and then Browse... to select the PATH_TO_THE_MELTS_MATLAB_PACKAGE_FOLDER.
If there is no 'Path' variable for the your_user_name account then select 'New...' instead. Put 'Path' for the Variable name (without the quotes) and 'Browse Directory...' to set the Variable value to the PATH_TO_THE_MELTS_MATLAB_PACKAGE_FOLDER.

Warning: do not edit or delete the existing folders in the user's Path or you may break existing software installations. And please do not edit the System PATH variable.

Test your installation by running the tutorial.py file or tutorial.ipynb notebook in the examples directory.

Installing on Linux

SYSTEM REQUIREMENTS

alphaMELTS for Python requires a C compiler be installed. Most laptop or desktop installations of Linux will include a compiler, but the WSL installation of Ubuntu does not by default. We recommend you install clang (sudo apt install clang) but gcc will work too.

alphaMELTS for Python also uses the GNU Science Library (GSL). On Linux it can be installed via the package manager (e.g. apt install gsl-bin on Ubuntu). It can also be downloaded directly but this has not been tested with alphaMELTS for Python.

INSTALLING and UPDATING

When a new release becomes available, make sure GSL is up to date (sudo apt update, then sudo apt upgrade). Then simply download the new package and replace the old files.

RUNNING alphaMELTS for Python (Linux)

For now, until alphaMELTS for Python is properly packaged (e.g. so that it can be installed via pip or conda), you will need to set the PYTHONPATH environment variables to include the path to 'MELTS_Matlab/package', or whatever the folder is called on your system. There are various ways to do that. One way is to open a terminal and type export PATH=$PATH:PATH_TO_THE_MELTS_MATLAB_PACKAGE_FOLDER. Then open the IDE from the terminal command line e.g. type code . to open VS Code.

Test your installation by running the tutorial.py file or tutorial.ipynb notebook in the examples directory.