- 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
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
In a fresh notebook we first load the package:
<<xAct`PSALTer`;
Next, we define Lagrangian couplings 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 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:
Wolfram Language | Output format | Meaning |
---|---|---|
a , b , c , ..., z
|
|
Cartesian coordinate indices |
G[-m,-n] |
Minkowski metric | |
CD[-m]@ |
Partial derivative |
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 ofFieldNameValue
, if any.SymmValue
is the intended index-symmetry onIndsValue
. The syntax is the same as inDefTensor
.PrintAsValue
is the string thatFieldNameValue
will use as format. The syntax is the same as inDefTensor
.PrintSourceAsValue
is the string that the source conjugate toFieldNameValue
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 usingDefField
. Each term must be linear in coupling constants defined usingDefConstantSymbol
from xTensor. Other allowed ingredients areCD
acting on field(s)FieldNameValue
andG
used to contract indices. Do not use an odd power ofepsilonG
, 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 be1
,2
or3
. This sets the maximum positive integer$n$ for which the$1/k^{2n}$ null pole residues are requested. The default is1
, 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)
- Prepare. Make sure your system satisfies all the requirements.
- 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
- 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/
- Prepare. Make sure your system satisfies all the requirements.
- 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
- 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/
- Make sure you've read the known bugs that can affect macOS users.
- Prepare. Make sure your system satisfies all the requirements.
- 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
- 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\"
- 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.
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:
- A reliable error on macOS generating the messages
RunProcess::pnfd
andImport::fmterr
. As suggested by the messages, checkEnvironment["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 usingwhich inkscape
in zsh, and amend the path accordingly in the notebook usingSetEnvironment
. - 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. - 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.
- 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.