Quick Start Guide

Installation

To get started with SpectraMatcher, you can either run the installation wizard for Windows or Linux, or launch it directly with Python.

Windows

SpectraMatcher works on Windows 7 and newer.

To install:

1. Download the latest .exe from the windows_installer directory of the repository.

2. Run the installation wizard and follow the on-screen instructions. It is recommended to keep the default installation directory.

No Python or additional setup is needed. Once installed, you can open SpectraMatcher from the Start Menu or by double-clicking any .smp vibronic analysis project file.

💡 If Windows SmartScreen shows a warning, click “More info” → “Run anyway”.

Linux

The provided SpectraMatcher binary requires glibc version 2.31 or newer, which is typically available on Ubuntu 20.04+, Debian 11+, Fedora 32+, and most other Linux distributions released since 2020. To install it, follow these steps:

1. Download the latest installer from the linux_installer directory of the repository.

2. Unzip the archive:

   unzip SpectraMatcher_Linux_Installer_1.1.0.zip
   cd SpectraMatcher_Linux

3. Make the installer executable:

   chmod +x install_spectramatcher.sh

4. Run the installer with root permissions:

   sudo ./install_spectramatcher.sh

   This will:

   • Copy the application to /opt/SpectraMatcher

   • Install a launcher and icon

   • Register the .smp file extension

   • Create a Start Menu entry and optional desktop shortcut

After installation, you can launch SpectraMatcher from the Start Menu, the desktop shortcut, or by running /opt/SpectraMatcher/SpectraMatcher in a terminal. You can also open .smp project files directly by double-clicking.

Run from Source (Python)

SpectraMatcher can also be run directly from source using Python 3.7 or newer. This is useful if you want to contribute to development or run on platforms not supported by the precompiled installer.

1. Clone the repository

git clone https://github.com/giogina/SpectraMatcher.git
cd SpectraMatcher

2. Install dependencies

Windows

Python 3.8+

On recent Windows and Python versions, install the required libraries with:

pip install -r requirements/win-latest.txt

Python 3.7

On Windows 7, only Python 3.7 is supported. Install the compatible versions of the dependencies with:

pip install -r requirements/win7.txt

If any packages fail to install due to missing downloads, use the backup wheels. Make sure the provided .dll files remain in the main directory — some may be missing from default Windows 7 setups.

To run SpectraMatcher:

python main.py

Or to open a project file directly:

python main.py -open file.smp

Linux / macOS

First, install the required system packages:

# On Debian/Ubuntu:
sudo apt install python3-tk wmctrl xclip

Then, install the Python dependencies:

Python 3.8+

pip install -r requirements/unix.txt

Python 7

For Python 3.7, older library versions are needed, which are installed with:

pip install -r requirements/unix37.txt

To start SpectraMatcher:

python3 main.py

Or to open a file directly:

python3 main.py -open file.smp

Starting a New Project

When you launch SpectraMatcher, the startup dashboard lets you open a recent project or create a new one.

💡 Select a recent project using the 🡻 🡹 keys, Enter to open, Escape to close.

When you start a new project, you may add your data files right away by clicking the folder icon or dragging files into the import area (Windows only).

Vibronic spectra analysis sessions are stored in project files using the .smp extension, which by default are saved in a {home}/SpectraMatcher/ directory.

Data Import

After creating a project, you’ll be taken to the Import Data tab. This screen shows all files available for analysis, together with their types (such as Gaussian output files, or experimental vibronic spectra), and an overview of their contents (e.g. the computation methods, level of theory, and first vibrational frequencies).

If you added data in the setup screen, they’ll already be listed in the left-hand panel. You can add more files at any time by:

• Clicking the “Add file” or “Add folder” buttons in the top-right, or

• Dragging and dropping files or folders into the left panel (Windows only).

Click the Auto Import button to automatically gather and import compatible data.

💡 Auto Import checks for consistency in geometry, method, and 0–0 transition energy. You can also manually assign files by dragging them into the corresponding slots.

For supported file types and further import options, see the Data Import section.

When you're ready, click Done to proceed to the spectrum viewer.

Emission and Excitation Vibronic Spectra

Once data is imported, the Emission and Excitation tabs display both the experimental spectrum (white) and computed spectra (colored by excited state).

The experimental spectrum appears at the bottom (white), and any computed excited states are shown above it.

You can:

• Toggle and manipulate spectra in the left-hand list,

• Move and scale individual spectra directly in the plot,

• Adjust peak widths and anharmonic correction factors of the computed spectra,

• Display customizable transition labels,

• Refine the detected experimental peaks,

• Or visualize individual vibrational modes.

💡 Changes are reflected immediately — no need to reprocess or reload.

For details on intensity scaling, shifting spectra, and adjusting anharmonic correction factors, see the Spectra Controls section.

Automatic Peak Matching

Once the computed spectra are satisfactorily aligned with the experiment, automatic peak matching can be enabled by checking the Match Peaks box near the bottom of the right-hand panel.

SpectraMatcher will then assign the corresponding peaks between the experimental and computed spectra, based on wavenumber proximity and relative intensity. Matched peaks are indicated by vertical lines, and a detailed assignment table is generated.

For advanced matching options and details on how scores are computed, see the Matching section.

Export of Results

Once the spectra are aligned and peaks have been matched, SpectraMatcher allows you to export your results in several convenient formats.

Assignment Table

The table of matched peaks — including wavenumbers, intensities, and transition labels — can be exported as:

• Tab-separated values for spreadsheets or data processing

• Word (.docx) for inclusion in reports

• LaTeX (.tex) for publication-ready formatting

Choose your preferred format from the menu at the bottom of the Match Settings dropdown, and use the Copy Table button to copy the table to your clipboard.

Convoluted Vibronic Spectrum Data

To export numerical data for the convoluted computed spectra, open the Composite Spectrum dropdown, check the spectra you want to export, and click Copy selected spectra to copy the full spectrum, as tab-separated text, to your clipboard.

This data includes wavenumber–intensity pairs and can be pasted directly into analysis tools or plotting software.

Plot

Export of the displayed plot is not currently implemented, but you can simply take a screenshot.

💡 Click the moon icon on the top right to toggle the spectrum between dark and light mode. Use the Snipping Tool on Windows or Shift+PrtScr on Linux to take a screenshot of only your desired area.

For more options and export formats, see the Export section.