I/O

SeQuant provides different forms of I/O for its objects. Generally, they can be found in the sequant::io namespace. Different formats live in different sub-namespaces. E.g. sequant::io::latex::to_string() yields a LaTeX representation of the respective object.

Note

Frequently used I/O functions also have shorthands that can be brought in by including the sequant/core/io/shorthands.hpp header. These shorthands live directly in the sequant namespace. The example from above could be achieved via sequant::to_latex() once that header is included.

LaTeX

The relevant function is sequant::io::latex::to_string(). SeQuant provides support for LaTeX conversion on most object types. If the shorthands header is included, this functionality is also exposed as sequant::to_latex().

The produced LaTeX code is not self-contained. It needs to be embedded in a suitable math environment. Furthermore, it assumes that the tensor has been loaded.

Warning

Some objects also have a to_latex() member function. However, we don’t provide any guarantees about which types do and they may also be removed in future SeQuant versions. Hence, you should always prefer using sequant::io::latex::to_string().

Note

The produced LaTeX code is typically not human-friendly (that is, hard to read) but should compile successfully once embedded in a suitable LaTeX document.

Serialization

SeQuant provides serialization support. This means that SeQuant objects can be transformed into some intermediary storable format (serialization), which can later be converted back (deserialization) to yield the original SeQuant object.

Functions associated with this live in the sequant::io::serialization namespace. At the moment, there is only a text format implemented via to_string() and from_string(). More formats may be added at a later point. It is important to note that in order to work with C++’s type system, from_string() is a template that takes in the type of object it is supposed to produce. The most important variants are from_string and from_string where the former also allows to deserialize any Expr subclass. Depending on the used template type, the expected format of the input will change accordingly.

As SeQuant’s capabilities develop over time, it can be necessary to adapt the syntax of the serialization format. By default, the abovementioned functions will always adhere to the latest parse syntax specification. However, they can be instructed to work with a different version by explicitly specifying a SerializationSyntax when calling them or using one of the versioned function calls.

Warning

All syntax versions except SerializationSyntax::Latest are considered deprecated. Support for them will remain available for some time but might get removed in future versions of SeQuant.

If the shorthands header is included, text-based serialization and deserialization is available as sequant::serialize() and sequant::deserialize.

Customizations

The exact serialization format can be customized to some extend by providing SerializationOptions and DeserializationOptions instances when calling the respective functions. Among other things, they allow for specification of a specific SerializationSyntax. For an overview of all customization options, please refer to the documentation of those classes in the API reference.

Note

Typically, you should leave these at their defaults to yield the most reliable behavior.

SerializationSyntax

We will loosely follow EBNF syntax for specifying the rules of the grammar describing the parse syntax. However, we don’t define a full formal grammar here as minor details and precedence issues may be left out/simplified in order to increase readability.

V1

Note

Known limitations:

• No support for second-quantized (normal-ordered) operators

• No support for complex numbers

• No support for representing operators (e.g. symmetrizers) explicitly

Component	Rule	Note
Result	(Tensor | Variable) (‘=’ | ‘<-’) Expression
Expression	Sum?
Sum	Product ( (‘+’ | ‘-’) Product)*
Product	Nullary ( ‘*’? Nullary )*	Explict ‘*’ use is optional
Nullary	‘(’ Sum ‘)’ | Number | Tensor | Variable
Number		Integer, Floating point or fraction
Tensor	Name IndexGroup SymmetrySpec?
IndexGroup	‘{’ IndexList? ( ‘;’ IndexList? ( ‘;’ IndexList? )? )? ‘}’ ‘^{’ IndexList? ‘}_{’ IndexList ‘}’ ‘_{’ IndexList? ‘}^{’ IndexList ‘}’	Meaning is {<bra>;<ket>;<aux>} Meaning is ^{<ket>}_{<bra>} (no aux) Meaning is _{<bra>}^{<ket>} (no aux)
IndexList	Index ( ‘,’ Index )?
Index	IndexSpaceName ‘_’? Integer
IndexSpaceName		Name but no undersore allowed
SymmetrySpec	‘:’ ( [ASN] ( ‘-’ [SCN] ( ‘-’ [SN] )? )? )	:<Symmetry>-<BraKetSymmetr>-<ColumnSymmetry>
Variable	Name
Name		Single word (may include Unicode chars)

sequant::io::serialization::from_string will start at rule Expression, whereas sequant::io::serialization::from_string will start at Result.

Examples

R1{u1;i1} = f{u1;i1} - Ym1{u1;u2} f{u2;i1} - Ym1{u3;u2} * g{u1,u2;u3,i1} + 1/2 Ym2{u1,u4;u_2,u_3} g{u2,u3;u4,i1}:A-C-N