• Updated README.md.

Copyright © 2022 Will Barker, Carlo Marzo and Claire Rigouzzo.

PSALTer is distributed as free software under the GNU General Public License (GPL).

PSALTer is provided without warranty, or the implied warranty of merchantibility or fitness for a particular purpose.

If PSALTer was useful to your research, please cite us using the following BibTeX:

@article{Barker:2024juc,
    author = "Barker, Will and Marzo, Carlo and Rigouzzo, Claire",
    title = "{PSALTer: Particle Spectrum for Any Tensor Lagrangian}",
    eprint = "2406.09500",
    archivePrefix = "arXiv",
    primaryClass = "hep-th",
    month = "6",
    year = "2024"
}

PSALTer is a software package for Mathematica designed to predict the propagating quantum particle states in any tensorial field theory, including (but not limited to) just about any theory of gravity. The free action $S_{\text{F}}$ must have the structure

where the ingredients are:

• The dynamical fields $\zeta(x)$ are real tensors, which may be a collection of distinct fields, each field having some collection of spacetime indices ($\mu$, $\nu$, etc.), perhaps with some symmetry among the indices.
• The wave operator $\mathcal{O}(\partial)$ is a real, second-order (Ostrogradsky's theorem discourages higher-derivative operators, but even if it did not we note that the apparent order may always be lowered by the introduction of extra fields) differential operator constructed from the flat-space metric $\eta_{\mu\nu}$ and partial derivative $\partial_\mu$ (but not the totally antisymmetric $\epsilon^{\mu\nu\sigma\lambda}$ tensor), linearly parameterised by a collection of coupling coefficients.
• The source currents $j(x)$ are conjugate to the fields $\zeta(x)$. They encode all external interactions to second order in fields, whilst keeping the external dynamics completely anonymous.

As a demonstration, we consider the Fierz-Pauli linearised massive gravity theory

where $\alpha$ and $\beta$ are coupling coefficients, $h_{\mu\nu}$ is the metric perturbation with trace $h\equiv h_{\mu}^{\mu}$, and $T^{\mu\nu}$ is the linearised stress-energy tensor of matter, which is the source conjugate to $h_{\mu\nu}$.

In a fresh notebook we first load the package:

<<xAct`PSALTer`;

Next, we define Lagrangian couplings $\alpha$ and $\beta$ as Coupling1 and Coupling2 using the command DefConstantSymbol from xAct:

DefConstantSymbol[Coupling1,PrintAs->"\[Alpha]"];
DefConstantSymbol[Coupling2,PrintAs->"\[Beta]"];

Next, we use the command DefField from PSALTer to define the metric perturbation $h_{\mu\nu}$ as the symmetric, rank-two tensor field MetricPerturbation:

DefField[
    MetricPerturbation[-a,-b],
    Symmetric[{-a,-b}],
    PrintAs->"\[ScriptH]",
    PrintSourceAs->"\[ScriptCapitalT]"
];

The output should look like:

To compute the spectrum, we plug the Lagrangian into the ParticleSpectrum function from PSALTer:

ParticleSpectrum[
    Coupling1*(
	(1/2)*CD[-b]@MetricPerturbation[a,-a]*CD[b]@MetricPerturbation[c,-c]
	-CD[a]@MetricPerturbation[-a,-b]*CD[b]@MetricPerturbation[c,-c]
	-(1/2)*CD[-c]@MetricPerturbation[a,b]*CD[c]@MetricPerturbation[-a,-b]
	+CD[-b]@MetricPerturbation[a,b]*CD[c]@MetricPerturbation[-a,-c]
    )
    +Coupling2*(
        MetricPerturbation[-a,-b]*MetricPerturbation[a,b]
        -MetricPerturbation[a,-a]*MetricPerturbation[b,-b]
    ),
    TheoryName->"MassiveGravity",	
    Method->"Easy",
    MaxLaurentDepth->3
];

The output should look like:

The documentation notebook is at PSALTer/xAct/PSALTer/Documentation/English/Documentation.nb. It is recommended to also read the paper.

When you first run <<xAct`PSALTer` the software defines a Minkowski manifold with the ingredients:

PSALTer defines two functions. To define a tensor field you use DefField, which has a very similar syntax to DefTensor in xTensor:

DefField[
    FieldNameValue_[IndsValue___],
    SymmValue_,
    PrintAs->PrintAsValue_,
    PrintSourceAs->PrintSourceAsValue_
];

The arguments and options are as follows:

• FieldNameValue is the symbolic name of the new field.
• IndsValue are the indices of FieldNameValue, if any.
• SymmValue is the intended index-symmetry on IndsValue. The syntax is the same as in DefTensor.
• PrintAsValue is the string that FieldNameValue will use as format. The syntax is the same as in DefTensor.
• PrintSourceAsValue is the string that the source conjugate to FieldNameValue will use as format.

To compute a spectrum, use ParticleSpectrum:

ParticleSpectrum[
    LagrangianValue_,
    TheoryName->TheoryNameValue_,
    Method->MethodValue_,
    MaxLaurentDepth->MaxLaurentDepthValue_
];

The arguments and options are as follows:

• LagrangianValue must be a valid linearised Lagrangian density. The expression must be a Lorentz-scalar. Each term must be quadratic in the field(s) FieldNameValue defined using DefField. Each term must be linear in coupling constants defined using DefConstantSymbol from xTensor. Other allowed ingredients are CD acting on field(s) FieldNameValue and G used to contract indices. Do not use an odd power of epsilonG, which will result in a parity-odd theory. Do not include the term coupling the fields to their conjugate sources: this is automatically included.
• TheoryNameValue can be any string. This is used for labelling the output files.
• MethodValue can be either of the strings "Easy" (default) or "Hard" (experimental, uses home-brewed implementations of the symbolic Moore-Penrose inverse and other innovations).
• MaxLaurentDepthValue can be 1, 2 or 3. This sets the maximum positive integer $n$ for which the $1/k^{2n}$ null pole residues are requested. The default is 1, from which the massless spectrum can be obtained. Setting higher $n$ naturally leads to longer wallclock times, but also allows potential (pathological) higher-order/non-simple propagator poles to be identified, down to the requested depth.

• A multi-core processor (recommended, note that most modern PCs are multi-core)
• An internet connection (recommended for PSALTer to interrogate the Wolfram Function Repository)

• Linux (recommended, tested on Linux v 6.9.1 via Manjaro, Arch, RockyLinux 8 (RHEL8) and CentOS7 (RHEL7))
• macOS (not recommended, tested on macOS Monterey)
• Windows (not recommended, tested on Windows 10)

• Mathematica (required, tested on Mathematica v 14.0.0.0)
• xAct (required packages xTensor, SymManipulator, xPerm, xCore, xTras and xCoba, tested on xAct v 1.2.0)
• RectanglePacking (recommended, tested on RectanglePacking v 1.0.0)
• Inkscape (recommended for Linux and macOS only, tested on Inkscape v 1.3.2)

1. Prepare. Make sure your system satisfies all the requirements.
2. Download. You can download the latest release from the panel on the right, and unzip using:

[user@system ~]$ unzip ~/Downloads/PSALTer*
[user@system ~]$ mv ~/PSALTer* ~/PSALTer

Alternatively, if you have git installed, the following bash command will download PSALTer into the home directory:

[user@system ~]$ git clone https://github.com/wevbarker/PSALTer

3. Install. To perform the installation, the sources need only be copied to the location of the other xAct sources. For a global installation of xAct this may require:

[user@system ~]$ cd PSALTer/xAct
[user@system xAct]$ sudo cp -r PSALTer /usr/share/Mathematica/Applications/xAct/

For a local installation of xAct, the path may be vary:

[user@system xAct]$ cp -r PSALTer ~/.Mathematica/Applications/xAct/

1. Prepare. Make sure your system satisfies all the requirements.
2. Download. You can download the latest release from the panel on the right, and unzip using:

user@system ~ % unzip ~/Downloads/PSALTer*
user@system ~ % mv ~/PSALTer* ~/PSALTer

Alternatively, if you have git installed, the following zsh command will download PSALTer into the home directory:

user@system ~ % git clone https://github.com/wevbarker/PSALTer

3. Install. To perform the installation, the sources need only be copied to the location of the other xAct sources. For a global installation of xAct this may require:

user@system ~ % cd PSALTer/xAct
user@system xAct % sudo cp -r PSALTer /Library/Mathematica/Applications/xAct/

For a local installation of xAct, the path may be vary:

user@system xAct % cp -r PSALTer ~/Library/Mathematica/Applications/xAct/

4. Make sure you've read the known bugs that can affect macOS users.

1. Prepare. Make sure your system satisfies all the requirements.
2. Download. You can download the latest release from the panel on the right, and unzip in File Explorer using right-click and Extract All. Alternatively, if you have git installed, the following cmd command will download PSALTer into the home directory:

C:\Users\user> git clone https://github.com/wevbarker/PSALTer

3. Install. To perform the installation, the sources need only be copied to the location of the other xAct sources. For a global installation of xAct, you may need to open File Explorer using right-click and Run as administrator. Alternatively, use the following cmd commands (again, opening cmd using Run as administrator):

C:\Users\user> cd PSALTer
C:\Users\user\PSALTer> xcopy /e /k /h /i xAct\ "C:\Program Files\Wolfram Research\Mathematica\14.0\AddOns\Applications\xAct\"

For a local installation of xAct, the path may be vary:

C:\Users\user\PSALTer> xcopy /e /k /h /i xAct\ "C:\Users\user\AppData\Roaming\Mathematica\Applications\xAct\"

4. Make sure you've read the known bugs that can affect Microsoft Windows users.

There are several ways to get help:

• The xAct google group contains a well established, highly active and very friendly community of researchers. Feel free to start a New conversation by posting a minimal working example of your code.
• For private correspondence, you can email us at [email protected].
• Alternatively you may wish to raise a New issue on GitHub.

Currently, all the known bugs affect just the production of the final output graphic and PDF file. The process of producing a vectorised, publication-grade graphic is convoluted; information boxes have to be exported as temporary PDF files, converted to EPS files using Inkscape (not on Microsoft Windows), and re-imported as vector graphics to be rectangle-packed and re-exported again. Currently, this is a process which works well only on Linux.

⚠️ If you just want to get the science results, without the PDF, you should run in your notebook the line xAct`PSALTer`Private`$NoExport=True before using DefField or ParticleSpectrum. This is a temporary fix, and will result in a less compact form of final output graphic that is not exported to a PDF. You can still try to export this graphic manually using the drop-down menus.

If you decide to continue with the default behaviour, you may encounter the following errors:

1. A reliable error on macOS generating the messages RunProcess::pnfd and Import::fmterr. As suggested by the messages, check Environment["PATH"] in your notebook. The result should include the path of the directory containing the Inkscape binary on your system. You can find out where that binary is located using which inkscape in zsh, and amend the path accordingly in the notebook using SetEnvironment.
2. A sporadic error on all operating systems generating the messages Transpose::nmtx, FindPermutation::norel, MapThread::mptd, Part::partw. The cause of this is not clear.
3. A reliable error on macOS and Microsoft Windows involving more-or-less misplaced glyphs in the output graphic. This happens when PSALTer is unable to use Inkscape on the system (the default case for Microsoft Windows), and so it defaults to re-importing the PDF graphics rather than converting to EPS. The Mathematica PDF importer is well-known to have lots of problems, and so it usually corrupts the figure to some extent.
4. A sporadic error on Linux and macOS involving missing or incorrect glyphs in the output graphic. This seems to happen when Inkscape was only partially successful. On Linux, the problem has to do with installed fonts, and it may be solved by upgrading your system (and rebooting).

This work used the DiRAC Data Intensive service (CSD3 www.csd3.cam.ac.uk) at the University of Cambridge, managed by the University of Cambridge University Information Services on behalf of the STFC DiRAC HPC Facility (www.dirac.ac.uk). The DiRAC component of CSD3 at Cambridge was funded by BEIS, UKRI and STFC capital funding and STFC operations grants. DiRAC is part of the UKRI Digital Research Infrastructure.

This work also used the Newton server, access to which was provisioned by Will Handley using an ERC grant.

PSALTer was improved by many useful discussions with Jaakko Annala, Stephanie Buttigieg, Will Handley, Mike Hobson, Manuel Hohmann, Damianos Iosifidis, Georgios Karananas, Anthony Lasenby, Yun-Cherng Lin, Oleg Melichev, Yusuke Mikura, Vijay Nenmeli, Roberto Percacci, Syksy Räsänen, Cillian Rew, Zhiyuan Wei, David Yallup, Haoyang Ye, and Sebastian Zell.

WB is grateful for the kind hospitality of Leiden University and the Lorentz Institute, and the support of Girton College, Cambridge. The work of CM was supported by the Estonian Research Council grants PRG1677, RVTT3, RVTT7, and the CoE program TK202 "Fundamental Universe". CR acknowledges support from a Science and Technology Facilities Council (STFC) Doctoral Training Grant.