| Larch: Data Analysis Tools for X-ray Spectroscopy

# 1. Downloading and Installation

The latest release version of Larch is 0.9.81.

Larch is in active and continuing development. We do not use a strict schedule, but for the past few years, new versions have typically been released every 3 months or so.

There are three ways to install Larch. Which of these is right for you will depend on your operating system and your familiarity with the Python programming language and environment:

> 1. Installing from a Binary installers. Use these to get started with Larix or other Larch GUI applications, or if you are not familiar with Python.

> 2. Installing with the GetLarch.sh and GetLarch.bat scripts. Use these if your comfortable with the command-line or want to customize your installation.

> 3. Installing into an existing Anaconda Python environment. Use this if you already have an Anaconda Python environment that you want to use.

There will not be any difference in the resulting code or packages when using these different methods. Each of these will result in a Python environment from which you can either use Larch and its GUI applications, or develop code with Larch. We recommend using the Binary installer on Windws, and the installation scripts on macOS or Linux, unless you know that you want to install into an existing Python environment.

## 1.1. Installing from a Binary installers

Table of Larch binary installers

> Operating System | Binary Installer File | Installation Notes
> --- | --- | ---
> Windows (64 bit) | Larch for Windows | Notes
> macOSX (64 bit) | Larch for MacOSX | Notes
> Linux (64 bit) | Larch for Linux | Notes

Binary installers for Windows, macOSX, and Linux are available at Larch Binary Installers. These are fairly large (more that 500 Mb files) self-contained files that will install a complete Anaconda Python environment with all of libraries needed by Larch. Normally, this installation will create a folder called xraylarch in your home folder – see platform-specific notes below.

Note

There can be no spaces in your username or the path in which Larch is installed.

If you have a space in your Windows username, you can probably install to `C:\Users\Public` - that has worked for some people!

Installing with these installer programs should write to files only to folders owned by the user account. It should not require administrative privilege and should not interfere with any thing else on your system (such as system Python).

These installers will also create a folder called Larch on your desktop that contains links (or shortcuts or Apps) to many of the Larch GUI applications listed in Table of Larch Applications and Programs. This includes tools for X-ray Absorption spectroscopy, X-ray fluorescence spectroscopy, and working with X-ray diffraction images.

### 1.1.1. Windows Notes

For Windows, download the Larch for Windows binary installer above and run it to install Larch. This will be installed to `C:\Users\<YourName>\xraylarch` for most individual Windows installations or to `C:\Users\<YourName>\AppData\Local\xraylarch` if your machine is part of a Windows Workgroup or Domain. As mentioned above, if your user name has a space in it, you will probably need to install to `C:\Users\Public`.

Alternatively you can download the GetLarch.bat script, and run that by double-clicking on it. This will download, install, and configure the Larch package, with a result that is nearly identical to the binary installer.

### 1.1.2. MacOS Notes

For MacOS, download the Larch for MacOSX package installer above and click it to install Larch. There are two important notes:

Note

MacOS will not install non-signed 3rd party packages by default. You may need to go into General Settings part of the Security & Privacy section of System Preferences and explicitly allow this package to be installed. You probably will be prompted for an Administrative password.

Note

You need to explicitly click on “Install only for me” during the installation process. If you get prompted for an Administrative password by the installer, go back and explicitly choose “Install only for me”.

Alternatively you can download the GetLarch.sh script, and run that in a Terminal session (Applications->Utilities->Terminal). This will download, install, and configure the Larch package, with a result that is nearly identical to the binary installer. If you run into any problems with permissions or administrative privileges or “unauthorized application” with the package installer, running this installer script actually avoids all of those issues since your user account will simply be running the commands to write files to your home directory.

### 1.1.3. Linux Notes

For Linux, use the GetLarch.sh script and run that in a Terminal session.

Desktop shortcuts as `.desktop` files will be created on all Linux platforms, but whether these actually appear on your desktop depends on the Windowing system used: they will appear on the desktop with KDE and many other systems, but not with Gnome. Clickable icons should also show up in the Applications selection of the “Start Menu” or Applications list.

## 1.2. Installing with the GetLarch.sh and GetLarch.bat scripts

This method is recommended on Linux, and for those who are relatively comfortable using a command-line, and is helpful for debugging cases where the binary installer has failed. The approach here is basically to run a script that follows the steps that the binary installer should follow, but is likely to give more useful error messages if something goes wrong. To install with this method, download and execute one of the following:

> - GetLarch.sh for Linux and Mac OSX

> - GetLarch.bat for Windows

Open a Shell or Terminal, find the location of this script and run that. On Windows, that would be launching the cmd program, and doing something like:

    cd C:\Users\<YOURNAME>\Downloads
    GetLarch

On macOS on Linux, open a Terminal (from Applications->Utilities->Terminal on macOS), and then type:

    cd Downloads
    sh GetLarch.sh

If this script fails, report it to the Larch Github Issues (including the error trace and the GetLarch.log file).

The scripts will download and install Mambaforge Python which uses Anaconda Python and the conda-forge channel as the basis of an installation that will be essentially identical to the environment installed by the binary installers, that is, the whole environment is stored in a folder called xraylarch in your home folder. In case of problems, simply remove this folder to clean the installation.

## 1.3. Installing into an existing Anaconda Python environment

If are already using an existing Anaconda Python, you may want to install Larch into that environment or create a new environment for it. This is definitely possible. Larch uses many of the common “scipy ecosystem” packages. The main packages that you may need to install that may not be installed are:

> - wxpython: needed for all plotting, graphics and GUI applications.

> - pymatgen: needed for handling CIF files to generate Feff input files.

> - openbabel: needed for converting some structure files to Feff input files.

> - tomopy: needed only for reconstructing X-ray fluorescence tomography.

To be clear, much of the core Larch functionality can be used as a library without these packages installed, but especially wxpython and pymatgen are heavily used and should be installed.

There is a conda-forge package for X-ray Larch, so from a shell it may be that all you need to do is run

    conda install -yc conda-forge xraylarch

To create a dedicated environment, can either use the conda-forge package or try something like this to first create a dedicated “scipy ecosystem” infrastructure and then install xraylarch with pip:

    mamba create -y --name xraylarch python=>3.11.5 scipy mkl_fft h5py matplotlib pandas
    mamba activate xraylarch
    mamba install -y -c conda-forge wxpython pymatgen jupyter "notebook<7.0"
    mamba install -y -c conda-forge scikit-image scikit-learn pycifrw plotly fabio pyfai
    mamba install -y -c conda-forge openbabel tomopy  # <- optional packages
    pip install "xraylarch[larix]"

Note

These commands use mamba because it is much faster that conda. If this fails, you may need to run conda install mamba

Note

Jupyter notebook version 7 and later does not work with plotly, and specifically with the example Jupyter notebooks use X-ray Larch.

Since the PyPI_ packages are the main release package, this method may better ensure that you get the latest version compared to installing the conda-forge package.

Finally, no matter how you install Larch, you can run

    larch -m

to create the Larch desktop application launchers or shortcuts.

## 1.4. Installing with pip into an existing Python environment

Larch relies on the “scipy ecosystem”, and has a large number of packages that it depends on. Most of these are available as binary (so-called “wheel” files) from PyPI, so that a simple

    pip install xraylarch

shoould work. Starting with version 0.9.73 9November, 2023), this command will work to install a fairly bare-bones set of tools – the basic xraylarch library, without requiring the packages needed to make any of the GUIs work.

In order to get the GUI-needed package, you could install with

    pip install xraylarch[larix]

(Note, you may need to type `pip install "xraylarch[larix]"` in some shells and terminals). This will also install all of the wxPython packages needed for the GUIs, as well as the libraries related to Jupyter.

The most notable missing binary package is the wxPython package on Linux. That means that if wxPython is not already installed, pip will try to compile it, which will almost certainly fail. This problem (which, in fairness to all involved, is very difficult to solve) is one of the main reasons we recommend using Anaconda Python - it provides this package in a consistent way. Anaconda Python also provides very good versions of almost all of hte “core scipy ecosystem” libraries. It also has good support for optional Intel Math Kernel libraries that will be used if available.

But, if you are not using Linux, or are using a system-provided Python that includes wxPython (and has it installed), it should be possible to install a runnable Larch library with

    pip install xraylarch

There are other optional addons that can be installed with Larch, such as

    pip install "xraylarch[dev]"

to add development and testing packages, or

    pip install "xraylarch[doc]"

to add tools needed to build the docs, or

    pip install "xraylarch[epics]"

to add tools needed to use the Epics controls system, or

    pip install "xraylarch[all]"

to install all these (and a few more packages)

## 1.5. Updating a previous installation

As new versions of X-ray Larch are released, they will be announced and pushed

to PyPI. This will allow updating can be done with

    pip install --upgrade xraylarch

For versions up to 0.9.68, XAS Viewer (now Larix) and other Larch Applications would notify users as updates became available and prompt them to install the latest version.

Note

Automatic updates using Larix (was XAS Viewer) have been unreliable for a long time, and can cause a non-working system, especially on Windows.

With version 0.9.70 and later, these notifications about updates are now informational and do not prompt for an immediate update. In addition, there is now a desktop shortcut called “Larch Updater” which will run the update pip command above.

## 1.6. Installing the development version

For the brave, a nightly build of the latest development version can be downloaded and installed with

    python -m pip install https://millenia.cars.aps.anl.gov/xraylarch/downloads/xraylarch-latest-py3-none-any.whl

We try to keep this working, but as this is an automated snapshot it might catch the development in the middle of trying to fix something tricky.

## 1.7. Making Desktop shortcuts to Link to the Applications

To make a Larch folder on your desktop with shortcuts (Windows or Linux) or Applications (MacOS) for the main Larch applications, you can then type

    larch -m

If that complains that it does not find larch, you may have to explicitly give the path to Python and/or Larch

    $HOME/xraylarch/bin/larch -m

from Linux or MacOSX or

    %APPDATA%\\Local\\xraylarch\Scripts\larch.exe -m

from Windows.

## 1.8. Larch for developers (source installation)

For developers, Larch is an open-source project, with active development happening at the Larch Repository (github.com). There, you will find the latest source code and pages for submit bug reports.

To get started, we recommend following the installation instructions for or ref:install-binary, ref:install-script, or ref:install-conda. That gives you a base starting Python environment that we can all be pretty sure is working. With that in place, to install Larch from source, you can clone the source repository with:

    git clone https://github.com/xraypy/xraylarch.git

and then install with:

    pip install -e .[all]

This use of pip will install any requirements and Larch itself, but those should have been installed already when you installed. Depending on your platform and version of Python you are installing to, you may need elevated permissions as from sudo to install Larch to a system folder.

### 1.8.1. Installing Optional Python Packages with Larch

While most of the packages required for Larch will be installed automatically (and are listed in the requirements.txt file in the source tree), there are a few packages that are useful for some functionality but somewhat less easy to have as a hard dependency (usually because they are not readily available on PyPI for all platforms). These optional packages are listed in the table below. Note that most of these will be installed with Larch whether you install from a binary installer with pip install xraylarch.

## 1.9. Getting Help

For questions about using or installing Larch, please use the Ifeffit Mailing List. For reporting bugs or working with the development process, please submit an issue at the Larch Github Pages.

## 1.10. Docs and Examples

The source kit includes sources for documentation in the docs folder and several examples (including all those shown in this documentation) in the examples folder.

These are also available separately in the zip file at Docs and Examples that contains a doc folder with this full documentation, and an examples folder with all of the Larch examples.

## 1.11. Citing Larch

Currently, the best citation for Larch is M. Newville, Larch: An Analysis Package For XAFS And Related Spectroscopies. Journal of Physics: Conference Series, 430:012007 (2013). [Newville (2013)]

## 1.12. Funding and Support

Larch development at the GeoScoilEnviroCARS sector of Center for Advanced Radiation Sources at the University of Chicago has been supported by the US National Science Foundation - Earth Sciences (EAR-1128799), and Department of Energy GeoSciences (DE-FG02-94ER14466). In addition, funding specifically for Larch was granted by the National Science Foundation - Advanced CyberInfrastructure (ACI-1450468).

## 1.13. Acknowledgements

Larch was mostly written by and is maintained by Matt Newville <newville@cars.uchicago.edu>. Bruce Ravel has an incalculable influence on the design and implementation of this code and has provided countless fixes for serious problems in design and execution in the early stages. More importantly, Larch would simply not exist without the long and fruitful collaboration we’ve enjoyed. Margaret Koker wrote most of the X-ray diffraction analysis code, and much of the advanced functionality of the GSECARS XRF Map Viewer. Mauro Rovezzi has provided the spec-data reading interface and the RIXS viewer. Tom Trainor had a very strong influence on the original design of Larch, and helped with the initial version of the python implementation. Yong Choi wrote the code for X-ray standing wave and reflectivity analysis and graciously allowed it to be included and modified for Larch. Tony Lanzirotti and Steve Sutton have provided wonderful and patient feedback on many parts of Larch, especially for XANES processing and testing of the Larix GUI.

Because Larch began as a rewrite of the Ifeffit XAFS Analysis Package, it also references and builds on quite a bit of code developed for XAFS over many years at the University of Chicago and the University of Washington. The existence of the code and a great deal of its initial design therefore owes a great thanks to Edward Stern, Yizhak Yacoby, Peter Livens, Steve Zabinsky, and John Rehr. More specifically, code written by Steve Zabinsky and John Rehr for the manipulation of results from FEFF and for the calculation of thermal disorder parameters for XAFS are included in Larch with little modification. Both Feff6l and Feff8l, the product of many man years of effort by the Feff group led by John Rehr, are included in Larch. A great many people have provided excellent bug reports, feedback, in depth conversations, and suggestions for making Ifeffit better, including on the ifeffit mailing list. Many of these contributions have found their way into Larch.

Larch uses X-ray scattering factors and cross-sections fro the xraydb library. This uses code to store and read the X-ray Scattering data from the Elam Tables was modified from code originally written by Darren S. Dale. Refined values for anomalous scattering factors there have been provided directly by Christopher T. Chantler. Further details of the origin of much of the tabularized X-ray data is given in X-ray Databases.

As Larch depends on the fantastic scientific librarie written and maintained in python, especially the numpy, scipy, and matplotlib, the entire scientific python community deserves a hearty thanks. In particular, Larch uses the lmfit library, which began as part of Larch but was spun off into a standalone, general purpose fitting library that became useful for application areas other than XAFS, and has benefited greatly from numerous collaborators and added many features that Larch, in turn, has been able to depend on.

## 1.14. License

Except where explicitly noted in the individual files, the code, documentation, and all material associated with Larch are distributed under the BSD License:

    BSD-2-CLAUSE LICENSE

    Copyright, Licensing, and Re-distribution
    -----------------------------------------

    Unless otherwise stated, all files included here are copyrighted and
    distributed under the following license:

    Copyright (c) 2010-2022 Matthew Newville, The University of Chicago
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice, this
      list of conditions and the following disclaimer.

    * Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.