xPlain: Formatting for Mathematical Derivations in Theoretical Physics

Version 0.0.0-developer

License

Copyright © 2023 Will E. V. Barker and Sebastian Zell

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

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

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

@misc{Barker:2023xPlain,
    author = "Barker, Will E. V. and Zell, Sebastian",
    title = "{xPlain: Formatting for Mathematical Derivations in Theoretical Physics}",
    year = "2023",
    note = "Part of the xAct bundle"
}

About

xPlain is a software package for Wolfram (formerly Mathematica) designed to format mathematical derivations in theoretical physics. It bridges the gap between programmatic computation and professional presentation by enabling both command-line and notebook interfaces while maintaining consistent, paper-quality mathematical typesetting.

The package addresses a fundamental challenge in theoretical physics: how to simultaneously:

• Retain the notebook front-end's mathematical formatting capabilities
• Present calculations with paper-style layout
• Work entirely in plaintext using professional development tools

xPlain is an (unofficial) part of the xAct bundle and implements the FAIR guiding principles for scientific data management. It is designed for unambiguous, lasting derivations in the Wolfram Language and is suitable for researchers who use the Wolfram Language programmatically.

The package has been successfully used in published supplemental materials, receiving positive feedback from anonymous referees: "It is remarkable the effort made by the authors with the Supplemental Material to show the connection between the Mathematica code employed for the computations and the statements in the paper."

Example: Basic Mathematical Document

As a demonstration, we consider formatting a simple mathematical derivation with sectioning, commentary, and cross-references.

In a fresh notebook we first load the package:

<<xAct`xPlain`;

Next, we create document structure using sectioning commands:

Title@"Welcome to the xPlain package, here is a title";
Chapter@"And here is a chapter";
Section@"And here is a section";
Subsection@"And here is a subsection";

We add commentary and define formatted variables:

Comment@"This is a comment. We will next type a numbered expression.";
Format@xx^=ToExpression@"\[ScriptX]";
DisplayExpression[xx,EqnLabel->"Eq1"];

For expressions that vanish, use the equation environment:

Comment@"And next we will type a numbered equation.";
DisplayEquation[xx,EqnLabel->"Eq2"];

Cross-references are handled automatically:

Comment@{"Here is a comment referring to",Cref@"Eq1",". We can also refer to multiple equations as",Cref@{"Eq1","Eq2"},"."};
Supercomment@{"Here is a comment referring to",Cref@"Eq1"," and multiple equations as",Cref@{"Eq1","Eq2"},"."};

The output is shown below:

Documentation

The package includes a comprehensive example notebook demonstrating all basic functionality. To run the examples:

[user@system xPlain]$ cp xAct/xPlain/Documentation/English/Examples.nb ~/Examples.nb
[user@system xPlain]$ cd ~
[user@system ~]$ wolframnb Examples.nb &

General use

Document Structure

The package provides hierarchical sectioning commands:

• Title["title text"] - Document title
• Chapter["chapter text"] - Chapter heading
• Section["section text"] - Section heading
• Subsection["subsection text"] - Subsection heading

Commentary and Display

• Comment["text"] or Comment[{"text", Cref["label"], "more text"}] - Regular commentary with optional cross-references
• Supercomment[...] - Emphasized commentary
• DisplayExpression[expr, EqnLabel->"label"] - Numbered mathematical expression
• DisplayEquation[expr, EqnLabel->"label"] - Numbered equation (implies vanishing)

Cross-referencing

• Cref["label"] - Reference to a single equation
• Cref[{"label1", "label2"}] - Reference to multiple equations
• Mref["label"] - Alternative reference format

Mathematical Formatting

Format variables using standard Wolfram Language conventions:

Format@myvar^=ToExpression@"\[ScriptM]";

Quickstart

Requirements

Basic hardware requirements

• A multi-core processor (recommended)
• An internet connection (recommended for package dependencies)

Operating systems

• Linux (recommended, tested on Linux v 6.15.8 via Arch and Manjaro)
• macOS (tested on macOS Monterey)
• Windows (tested on Windows 10)

Software dependencies

• Wolfram (formerly Mathematica) (required, tested on Wolfram v 13.1.0.0)
• xAct (required, tested on xAct v 1.2.0)

Installation

⚠️ Note that Mathematica was re-branded as Wolfram on July 31 2024 with the release of Wolfram v 14.1. You may still be able to install xPlain in older versions by replacing Wolfram with Mathematica in the paths below.

Linux

1. Prepare. Make sure your system satisfies all the requirements.
2. Download. Clone or download the repository:

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

3. Install. Use the provided installation script:

[user@system xPlain]$ ./install.sh

Alternatively, manually copy to your xAct installation:

[user@system xPlain]$ cp -r xAct/xPlain ~/.Wolfram/Applications/xAct/

For a global installation:

[user@system xPlain]$ sudo cp -r xAct/xPlain /usr/share/Wolfram/Applications/xAct/

macOS

1. Prepare. Make sure your system satisfies all the requirements.
2. Download. Clone or download the repository:

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

3. Install. Copy to your xAct installation:

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

For a global installation:

user@system xPlain % sudo cp -r xAct/xPlain /Library/Mathematica/Applications/xAct/

Microsoft Windows

1. Prepare. Make sure your system satisfies all the requirements.
2. Download. Clone or download the repository:

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

3. Install. Copy to your xAct installation:

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

For a global installation (run as administrator):

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

Getting help

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].
• You may wish to raise a New issue on GitHub.

Acknowledgements

This work was performed using resources provided by the Cambridge Service for Data Driven Discovery (CSD3) operated by the University of Cambridge Research Computing Service (www.csd3.cam.ac.uk), provided by Dell EMC and Intel using Tier-2 funding from the Engineering and Physical Sciences Research Council (capital grant EP/T022159/1), and DiRAC funding from the Science and Technology Facilities Council (www.dirac.ac.uk).

I am grateful for the kind hospitality of Leiden University and the Lorentz Institute, and am supported by Girton College, Cambridge.