• Admits arbitrary tensorial field theories in 3+1 dimensions.
• Admits field theory on flat spacetime, or a dynamical metric for gravity.
• Keeps track of canonical fields and their conjugate momenta.
• Computes Poisson brackets between canonical quantities.
• Re-expresses computed brackets in terms of index-free ansätze using integrations by parts and dimensionally dependent identities.
• Can be used by humans.
• Can be used by agents.

Copyright © 2023 Will E. V. Barker

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

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

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

@article{Barker:2025noc,
    author = "Barker, Will",
    title = "{Fast Poisson brackets and constraint algebras in canonical gravity}",
    eprint = "2512.25007",
    archivePrefix = "arXiv",
    primaryClass = "physics.comp-ph",
    month = "12",
    year = "2025"
}

Hamilcar is a software package for Wolfram (formerly Mathematica) designed to provide robust tools for agentic systems to perform Hamiltonian analysis in canonical field theory. The overall goal is to enable AI agents and automated systems to conduct sophisticated field theory calculations through well-defined interfaces.

The package focuses on canonical field theory calculations in 3+1 dimensions, where the action $S$ has the structure

where the ingredients are:

• The dynamical fields $\psi(x,t)$ are real tensors on the spatial manifold, which may be a collection of distinct fields, each field having some collection of spatial indices ($a$, $b$, etc.), perhaps with some symmetry among the indices.
• The conjugate momenta $\pi_\psi(x,t)$ are the canonical momenta conjugate to the fields $\psi(x,t)$.
• The Hamiltonian density $H(\psi,\pi_\psi)$ is constructed from the fields, momenta, spatial metric, and spatial derivatives.

As a demonstration, we consider a simple scalar field theory in 3+1 dimensions

where $m$ is the mass parameter.

In a fresh notebook we first load the package:

<<xAct`Hamilcar`;

Next, we define a scalar field using the command DefCanonicalField:

DefCanonicalField[Phi[],FieldSymbol->"\[Phi]",MomentumSymbol->"\[Pi]"];

We can then compute Poisson brackets between quantities:

PoissonBracket[Phi[],ConjugateMomentumPhi[]];

Documentation with general relativity as a worked example is available at xAct/Hamilcar/Documentation/English/. Currently, the documentation is programmatically generated from the Documentation.m script, which uses some custom packages to produce Documentation.nb and Documentation.pdf files. The notebook and PDF are readable, and display the relevant commands in code blocks, however the notebook is not meant to be interactive or executable. More standard documentation may be added in future releases. It is also recommended to read the associated paper (see top of this README).

While Hamilcar currently provides a comprehensive Mathematica interface for canonical field theory calculations, it is intended for integration with agentic systems. A rudimentary agent Hasdrubal is under development.

When you first run <<xAct`Hamilcar` the software defines a three-dimensional spatial hypersurface with the ingredients:

For those familiar with xAct, note that calls to DefManifold and DefMetric are made internally at this stage. The package establishes a spatial manifold M3, creating the necessary geometric structure for canonical field theory calculations.

DefCanonicalField[<Fld>[]]

defines a scalar canonical field <Fld> and its conjugate momentum ConjugateMomentum<Fld>.

DefCanonicalField[<Fld>[<Ind1>,<Ind2>,...]]

defines a tensor canonical field <Fld> and its conjugate momentum ConjugateMomentum<Fld> with indices <Ind1>, <Ind2>, etc..

DefCanonicalField[<Fld>[<Ind1>,<Ind2>,...],<Symm>]

defines a tensor canonical field <Fld> and its conjugate momentum ConjugateMomentum<Fld> with indices <Ind1>, <Ind2>, etc. and symmetry <Symm>.

• The syntax of DefCanonicalField follows similar patterns to DefTensor in xTensor.
• Any number of comma-separated indices may be drawn from the contravariant a, b, c, up to z, the covariant -a, -b, -c, up to -z, or any admixture.
• The symmetry <Symm> can be one of the following (or any admixture allowed by DefTensor):
  • Symmetric[{<SymmInd1>,<SymInd2>,...}] denotes symmetrized indices.
  • Antisymmetric[{<SymmInd1>,<SymInd2>,...}] denotes antisymmetrized indices.
• If the global variable $DynamicalMetric is set to True, then:
  • The spatial metric G is automatically registered as a canonical field, and ConjugateMomentumG is defined.
  • All conjugate momenta are automatically defined as tensor densities of weight one (the effects of this are only seen by the G-variations performed internally by PoissonBracket).
• The following options may be given:
  • FieldSymbol is the symbol that <Fld> will use for display formatting.
  • MomentumSymbol is the symbol that the conjugate momentum will use for display formatting.

PoissonBracket[<Op1>,<Op2>]

computes the Poisson bracket between operators <Op1> and <Op2>.

• The operators <Op1> and <Op2> must be expressions involving:
  • Canonical fields and their conjugate momenta which have been defined using DefCanonicalField.
  • Tensors which have been defined on the manifold M3 using DefTensor, and which are assumed always to be independent of the canonical fields.
  • Derivatives via CD of canonical and non-canonical quantities, the spatial metric G, and the totally antisymmtric tensor epsilonG.
  • Constant symbols which have been defined using DefConstantSymbol (or DefNiceConstantSymbol from the xTras package).
• The function automatically generates smearing tensors unless $ManualSmearing is set to True.
• When $DynamicalMetric is set to True, the G-sector contributions are included.
• The function computes variational derivatives with respect to all registered fields and momenta.

TotalFrom[<Expr>]

expands composite expressions to canonical variable form by applying all registered expansion rules.

• The function converts composite quantities (like constraint expressions, traces, or field combinations) into explicit expressions involving only the fundamental canonical variables: fields, conjugate momenta, and their spatial derivatives.
• This expansion is essential before computing Poisson brackets, as bracket calculations require expressions to be written in terms of the canonical variables registered by DefCanonicalField.
• The function applies all rules stored in the internal list $FromRulesTotal, which are populated using PrependTotalFrom.

TotalTo[<Expr>]

converts expressions from canonical variable form back to compact notation using registered contraction rules.

• The function performs the inverse operation of TotalFrom, converting expressions written in terms of canonical variables back to more compact composite notation.
• This is primarily used for presentation purposes to make final results more readable.
• The function applies all rules stored in the internal list $ToRulesTotal, which are populated using PrependTotalTo.
• Unlike TotalFrom, this function is optional in most calculations.

PrependTotalFrom[<Rule>]

registers an expansion rule to convert a composite quantity to canonical variable form.

• The function adds <Rule> to the front of the internal list $FromRulesTotal used by TotalFrom.
• Typically used with MakeRule expressions that define composite quantities in terms of canonical variables.
• Essential for setting up the expansion system before performing Poisson bracket calculations.
• Example usage: FromSuperHamiltonian//PrependTotalFrom registers the rule to expand the super-Hamiltonian constraint.

PrependTotalTo[<Rule>]

registers a contraction rule to convert canonical variable expressions back to compact notation.

• The function adds <Rule> to the front of the internal list $ToRulesTotal used by TotalTo.
• Used with rules that convert expanded canonical expressions back to composite quantities.
• Provides the symmetric counterpart to PrependTotalFrom for bidirectional transformations.
• Less commonly used than PrependTotalFrom as conversion back to compact form is often optional.

FindAlgebra[<Expr>,{{<Fctr1>,<Fctr2>,...},...}]

seeks to express <Expr> as a sum of any number of terms, where each term corresponds to one of the sub-lists and has factors corresponding to indexed tensors whose heads are <Fctr1>, <Fctr2>, etc., where those tensor heads were defined using DefCanonicalField or DefTensor. The re-expression is achieved automatically by means of any required number of integrations by parts.

FindAlgebra[<Expr>,{{<Fctr1>,<Fctr2>,...,{CD,...,<Fctr3>,...}},...}]

additionally admits terms where one or more applications of the spatial covariant derivative CD act on any of a select group of factors, here <Fctr3>, etc.

• The following options may be given:
  • Constraints is a list of special (and appropriately indexed) tensors which were passed as part of the ansatz, with respect to which the re-expression is expected to be homogeneously linear. The answer will be expressed with these tensors factored out.
  • Verify is a boolean which, when set to True, causes the re-expression and <Expr> to be varied internally with respect to any tensors which appear exactly to the first power in all terms, after an application of TotalFrom. This usually includes smearing functions, but it may also include some canonical variables. The equality of the variations is checked to ensure that the re-expression is correct. Default is False.
  • DDIs is a boolean which, when set to True, causes dimensionally dependent identities (DDIs) such as the Cayley-Hamilton theorem to be taken into account when performing the re-expression. Default is False.

This function is undocumented and under active development. The purpose of the function is to manage time derivatives of fields.

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

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

• Wolfram (formerly Mathematica) (required, tested on Wolfram v 14.2.0.0).
• xAct (required packages xTensor, SymManipulator, xPerm, xCore and xTras, tested on xAct v 1.2.0).

⚠️ 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 Hamilcar in older versions of Wolfram (formerly Mathematica) by replacing Wolfram with Mathematica in the various paths below.

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/Hamilcar*
[user@system ~]$ mv ~/Hamilcar* ~/Hamilcar

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

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

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 Hamilcar/xAct
[user@system xAct]$ sudo cp -r Hamilcar /usr/share/Wolfram/Applications/xAct/

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

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

⚠️ Note that macOS is not recommended for use with Hamilcar.

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/Hamilcar*
user@system ~ % mv ~/Hamilcar* ~/Hamilcar

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

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

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 Hamilcar/xAct
user@system xAct % sudo cp -r Hamilcar /Library/Mathematica/Applications/xAct/

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

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

⚠️ Note that Microsoft Windows is not recommended for use with Hamilcar.

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 Hamilcar into the home directory:

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

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 Hamilcar
C:\Users\user\Hamilcar> 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\Hamilcar> xcopy /e /k /h /i xAct\ "C:\Users\user\AppData\Roaming\Mathematica\Applications\xAct\"

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 [email protected].
• Alternatively you may wish to raise a New issue on GitHub.

Hamilcar was improved by useful discussions with Boris Bolliet, Justin Feng, Drazen Glavan, Will Handley, Carlo Marzo, Roberto Percacci, Syksy Rasanen, Alessandro Santoni, Ignacy Sawicki, Richard Woodard and Tom Zlosnik.

I am grateful for the support of Marie Sklodowska-Curie Actions and the Institute of Physics of the Czech Academy of Sciences.

I was supported by the research environment and infrastructure of the Handley Lab at the University of Cambridge.

This work was performed using the Cambridge Service for Data Driven Discovery (CSD3), part of which is operated by the University of Cambridge Research Computing on behalf of the STFC DiRAC HPC Facility (www.dirac.ac.uk). The DiRAC component of CSD3 was funded by BEIS capital funding via STFC capital grants ST/P002307/1 and ST/R002452/1 and STFC operations grant ST/R00689X/1. DiRAC is part of the National e-Infrastructure.

Co-funded by the European Union (Physics for Future - Grant Agreement No. 101081515). Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or European Research Executive Agency. Neither the European Union nor the granting authority can be held responsible for them.