Quelle _Chapter_FileFormat.xml Sprache: XML

<?xml version="1.0" encoding="UTF-8"?>


<Chapter Label="Chapter_FileFormat">
<Heading>Extended MTX (MTXE) File Format</Heading>


<Section Label="Chapter_FileFormat_Section_General_information">
<Heading>General information</Heading>


The code supports reading matrices from an MTX file using <Code>ReadMTXE</Code>
and writing new MTX file using <Code>WriteMTXE</Code> functions.
Below a description of the format is given.

<Subsection Label="Chapter_FileFormat_Section_General_information_Subsection_Representation_of_field_elements_via_integers">
<Heading>Representation of field elements via integers</Heading>


Every finite field is isomorphic to a Galois field <Math>F=\mathop{\rm GF}(q)</Math>, where
<Math>q</Math> is a power of a prime, <Math>q=p^m</Math>.

<List>
<Item>
For a prime field, with <Math>q=p</Math> a prime, <Math>F</Math> is a prime field, isomorphic to the
 ring Z<Math>(q)</Math> of integers modulo
 <Math>q</Math>. In such a case, elements of the field are stored
 directly as integers. After reading, these are taken modulo <Math>p</Math>,
 thus, e.g., with <Math>p=7</Math>, values <Math>-1</Math>, <Math>6</Math>, or <Math>13</Math> are all equivalent.
</Item>
</List>

<List>
<Item>
When <Math>q=p^m</Math> with <Math>m > 1</Math>, <Math>F</Math> is an extension field. Non-zero
 elements of such a field can be represented as integer powers of a
 primitive element <Math>\alpha</Math>, a primitive root of unity in the field.
 Primitive element is a root of a primitive polynomial <Math>f(x)</Math>, that
 is, an irreducible polynomial with coefficients in the corresponding
 prime field <Math>\mathop{\rm GF}(p)</Math>, with the property that the smallest integer <Math>n</Math>
 such that <Math>f(x)</Math> divides <Math>x^n-1</Math> is <Math>n=p^m-1</Math>. Alternatively, field
 elements can be represented as <Math>p</Math>-ary polynomials modulo the chosen
 primitive polynomial <Math>f(x)</Math>.
</Item>
</List>

 Either definition requires that the primitive polynomial be
 specified. By default, GAP uses Conway polynomials to represent
 field elements. For details, as well as a large collection of
 Conway polynomials, please see the web page maintained by Frank
 Luebeck <Cite Key="ConwayPol-2022"/>.

In the actual file format, three different and mutually exclusive
storage options for elements of an extension field can in be used.

<List>
<Item>
First, assuming all elements needed are actually in the
 corresponding prime field <Math>\mathop{\rm GF}(p)</Math>, the integer values (mod <Math>p</Math>)
 directly correspond to the values of field elements. This is the
 case, e.g., with <Math>0,\pm1</Math> matrices which obey the orthogonality
 condition already over integers, and retain orthogonality over
 Z<Math>(q)</Math> with any <Math>q</Math> (what is more relevant here, the same matrix
 would work with any prime field). (<Emph>this is currently not implemented</Emph>)
</Item>
</List>

<List>
<Item>
Second option, and the only option currently implemented for
 extension fields, is to store the powers of the primitive element
 for each non-zero element in the field, and <Math>-1</Math> for zero.
</Item>
</List>

<List>
<Item>
Third option, is to take the coefficients of <Math>p</Math>-ary polynomial
 <Math>a_0+a_1x+a_2x^2+\ldots +a_{m-1}x^{m-1}</Math> as
 digits of a <Math>p</Math>-ary integer <Math>(a_{m-1}a_{m-2}\ldots a_2a_1)_p</Math>.
 (<Emph>this is currently not implemented</Emph>)
</Item>
</List>

</Subsection>

<Subsection Label="Chapter_FileFormat_Section_General_information_Subsection_Matrix_storage_format">
<Heading>Matrix storage format</Heading>


There are two recommended storage formats.

1. For CSS matrices stored in
 separate files, the MTX header should use the <Code>integer</Code> type, with matrix
 elements stored in the usual order.

2. For general stabilizer codes, or to store both CSS matrices in a
 single file, the MTX header should use the <Code>complex</Code> type. In this
 case the block matrix <Math>(A,B)</Math> is stored as a complex matrix <Math>A+iB</Math>.

In both format versions, the number of columns specified in the file
coincides with the code length.

Two additional matrix format versions supported by <Code>ReadMTXE</Code> and
<Code>WriteMTXE</Code> are provided for compatibility. Here, the columns <Math>a_i</Math>
and <Math>b_i</Math> in the blocks <Math>A</Math> and <Math>B</Math> are listed individually, and are
either intercalated [the ordering <Math>(a_1, b_1,
a_2,b_2,\ldots,a_n,b_n)</Math>] or are separated into column blocks
<Math>(a_1,\ldots,a_n,b_1,\ldots,b_n)</Math>. In both cases the number of
columns in the matrix stored is twice the code length.

The ordering of the columns is governed by a parameter
<Code>pair</Code>, optional in the function <Code>ReadMTXE</Code> and required in <Code>WriteMTXE</Code>.

<List>
<Item>
With <Code>pair=0</Code> the matrix elements are stored in the usual order. In
 this case the MTX header should use the <Code>integer</Code> type. This is the
 defailt storage format for stabilizer generator matrices of CSS
 codes, and also the internal matrix format for single-block matrices
 accepted by the function <Code>DistRandCSS</Code>, see Section <Ref
 Sect="Section_DistanceFunctions"/>.
</Item>
</List>

<List>
<Item>
With <Code>pair=1</Code> the block matrix <Math>(A,B)</Math> is stored with intercalated
 columns <Math>(a_1,b_1,\ldots,a_n,b_n)</Math>; the MTX header should use the
 <Code>integer</Code> type. This is the internal matrix format for two-block
 matrices accepted by the functions <Code>DistRandStab</Code> (<Ref
 Sect="Section_DistanceFunctions"/>) and <Code>WriteMTXE</Code> (<Ref
 Sect="Section_IOFunctions"/>), and returned by <Code>ReadMTXE</Code> (<Ref
 Sect="Section_IOFunctions"/>).
</Item>
</List>

<List>
<Item>
With <Code>pair=2</Code> the block matrix <Math>(A,B)</Math> is stored with separated
 columns <Math>(a_1,\ldots,a_n, b_1,\ldots,b_n)</Math>; the MTX header should also
 use the <Code>integer</Code> type.
</Item>
</List>

<List>
<Item>
With <Code>pair=3</Code> the block matrix <Math>(A,B)</Math> is stored as a complex matrix
 <Math>A+iB</Math>, with columns <Math>(a_1 + i b_1,\ldots,a_n + i b_n)</Math>. In this
 case <Code>type=complex</Code>, since matrix elements are represented as
 complex integers.
</Item>
</List>

By default, <Code>pair=0</Code> corresponds to <Code>type=integer</Code> and <Code>pair=3</Code>
corresponds to <Code>type=complex</Code>. <Emph>It is strongly recommended</Emph> that
matrices intended for use by others should only use these two variants of
the MTXE format.

For efficiency reasons, the function <Code>DistRandStab</Code> (<Ref
Sect="Section_DistanceFunctions"/>) assumes the generator matrix with
intercalated columns.

</Subsection>

<Subsection Label="Chapter_FileFormat_Section_General_information_Subsection_Explicit_format_of_each_line">
<Heading>Explicit format of each line</Heading>


The first line must have the following form:
<#Include Label="MMXFormatLine1">

with <Code>type</Code> either <Code>integer</Code> or <Code>complex</Code>.

The second line is optional and specifies the field, the primitive
polynomial used (in the case of an extension field), and the storage
format of field elements.

<#Include Label="FieldHeaderA">


Here the records should be separated by one or more spaces;
while <Code>field</Code>, <Code>polynomial</Code>, and <Code>format</Code> <Emph>should not contain any spaces.</Emph>
Any additional records in this line will be silently ignored.

The <Code>field</Code> option should specify a valid field, <Code>GF(q)</Code> or
<Code>GF(p^m)</Code>, where <Math>q>1</Math> should be a power of the prime <Math>p</Math>.

The <Code>polynomial</Code> should be a valid expanded monic polynomial with
integer coefficients, with a single independent variable <Code>x</Code>; it
should contain no spaces. An error will be signaled if <Code>polynomial</Code>
is not a valid primitive polynomial of the <Code>field</Code>. This argument is
optional; if not specified, one may assume that the Conway polynomial
should be used.

The optional <Code>format</Code> string should be "AdditiveInt" (the default for
prime fields), "PowerInt" (<Emph>currently</Emph> the default for extension
fields with <Math>m>1</Math>) or "VectorInt".

<List>
<Item>
<Code>AdditiveInt</Code> indicates that values listed
 are expected to be in the corresponding prime field and should be
 interpreted as integers mod <Math>p</Math>.
</Item>
</List>

<List>
<Item>
<Code>PowerInt</Code> indicates that field elements are
 represented as integers powers of the primitive element, root of
 the primitive polynomial, or <Math>-1</Math> for the zero field element.
</Item>
</List>

<List>
<Item>
<Code>VectorInt</Code> corresponds to encoding coefficients of a degree-<Math>(m-1)</Math>
 <Math>p</Math>-ary polynomial representing field elements into a <Math>p</Math>-ary
 integer. In this notation, any negative value will be taken mod
 <Math>p</Math>, thus <Math>-1</Math> will be interpreted as <Math>p-1</Math>, the additive inverse of
 the field <Math>1</Math>.
</Item>
</List>

The primitive polynomial must be written
explicitly as <Math>x^m+a_{m-1}*x^{m-1}+\ldots+a_1*x+a_0</Math>, where the
integer coefficients <Math>a_i</Math> will be interpreted modulo <Code>p</Code>. <Emph>The primitive polynomial
should not contain any spaces.</Emph>

<#Include Label="MMXFormatLine2">


For example, with <Math>q=5^2</Math>, the Conway polynomial
<Math>f_{5,2}(x)=x^2-x+2</Math>, and the second line can read
<#Include Label="MMXFormatLine2A">


The following is an equivalent form of the
same polynomial and can also be used
<#Include Label="MMXFormatLine2B">

The field may be left undefined; by default, it is <Math>\mathop{\rm GF}(2)</Math>, or it can
be specified by hand when reading the matrices.
If the primitive polynomial is undefined, it will be assumed that the
Conway polynomial used internally by <Code>GAP</Code> should be used.

Next follows the comment section, with each line either empty or
starting with the <Code>%</Code> symbol:
<#Include Label="MMXFormatLine3">


After the comment section, in agreement with MTX format, goes the line
giving the dimensions of the matrix and the number of non-zero elements:
<#Include Label="MMXFormatLineA">


Then all non-zero elements are listed as three or four integers according to the <Code>type</Code>:

<List>
<Item>
<Code>type=integer</Code>:
</Item>
</List>
<#Include Label="MMXFormatLineB">


<List>
<Item>
<Code>type=complex</Code>:
</Item>
</List>
<#Include Label="MMXFormatLineC">


Notice that column and row numbers must start with 1, as prescribed in
the original MTX format.

</Subsection>

<Subsection Label="Chapter_FileFormat_Section_General_information_Subsection_Matrix_Storage_Implementation_Details">
<Heading>Matrix Storage Implementation Details</Heading>


Neither the <Code>WriteMTXE</Code> nor <Code>ReadMTXE</Code> currently support the <Code>Format:</Code>
parameter. Prime field elements are only stored "as is", i.e., as integers
to be taken modulo <Code>p</Code>, while extension field elements are only stored
in the <Code>PowerInt</Code> format, i.e., with the power of the primitive
element specified, or "-1" for zero.

The function <Code>WriteMTXE</Code> can only save field elements with the
primitive polynomial used internally by <Code>GAP</Code>, i.e., the Conway
polynomial.

The function <Code>ReadMTXE</Code> can read matrix elements specified (in the
case of an extension field) with any primitive polynomial as specified
in the file.

Given the field <Math>\mathop{\rm GF}(p^m)</Math> and the primitive polynomial <Math>p(x)</Math>
specified in the file, the function <Code>ReadMTXE</Code> first checks that the
degree of <Math>p(x)</Math> is indeed <Math>m</Math> and that it is a primitive polynomial
in the corresponding prime field <Math>\mathop{\rm GF}(p)</Math>. If either of these tests
fail, <Code>ReadMTXE</Code> produces an error. Otherwise, it will attempt to
find the conversion coefficient <Math>c</Math> such that <Math>\alpha^c</Math> is a root of
<Math>p(x)</Math>, starting with <Math>c=1</Math>. When found, the multiplicative inverse
<Math>s</Math> such that <Math>sc\equiv 1\bmod (q-1)</Math> will be used to convert the
elements being read, i.e., for any matrix element <Math>y</Math> read, <Math>y^s</Math> will
be used instead.

Notice that, unless the Conway polynomial was used (in which case
<Math>c=s=1</Math>, and the conversion is trivial), this search can be slow for
large fields, as all integer values in <Math>[1,2,\ldots,q-2]</Math> will be
tested sequentially. To help ensure that the correct polynomial is
used, it is recommended that orthogonality of matrices be checked.

</Subsection>

</Section>

<Section Label="Chapter_FileFormat_Section_Example_MTXE_files">
<Heading>Example MTXE files</Heading>


In this section we give two sample MTXE files storing the stabilizer generator
matrix of 5-qubit codes.

First, matrix (with one redundant linearly-dependent row) stored with
<Code>type=integer</Code> and <Code>pair=1</Code> (intercalated columns
<Math>[a_1,b_1,a_2,b_2,\ldots]</Math>) is presented. Notice that the number of
columns is twice the actual length of the code. Even though the field
is specified explicitly, this matrix would work with any
prime field.

<#Include Label="SampleFileA">


This same matrix is stored in the file <Code>matrices/n5k1A.mtx</Code>. This is
how the matrix can be read and distance calculated:
<Example><![CDATA[
gap> filedir:=DirectoriesPackageLibrary("QDistRnd","matrices");;
gap> lis:=ReadMTXE(Filename(filedir,"n5k1A.mtx" ));;
gap> Print("field ",lis[1],"\n");
field GF(7)
gap> dist:=DistRandStab(lis[3],100,0 : field:=lis[1]);
3
]]></Example>


The same matrix can also be stored with <Code>type=complex</Code> and <Code>pair=3</Code>
(complex pairs <Math>[a_1+i b_1,a_2+i b_2,\ldots]</Math>). In this format, the
number of columns equals the code length.

<#Include Label="SampleFileB">


The matrix above is written in the file <Code>matrices/n5k1.mtx</Code>. To
calculate the distance, we need to specify the field [unless we want
to use the default binary field].

<Example><![CDATA[
gap> lis:=ReadMTXE(Filename(filedir,"n5k1.mtx" ));;
gap> Print("field ",lis[1],"\n");
field GF(2)
gap> dist:=DistRandStab(lis[3],100,0,2 : field:=lis[1]);
3
gap> q:=17;;
gap> lis:=ReadMTXE(Filename(filedir,"n5k1.mtx") : field:= GF(q));;
gap> Print("field ",lis[1],"\n");
field GF(17)
gap> dist:=DistRandStab(lis[3],100,0,2 : field:=lis[1]);
3
]]></Example>


Finally, the following is an example of a five-qudit code over
<Math>\mathop{\rm GF}(2^3)</Math> constructed by the script <Code>examples/cyclic.g</Code>.
<#Include Label="SampleFileC">


</Section>


</Chapter>

quality90%

¤ Dauer der Verarbeitung: 0.13 Sekunden (vorverarbeitet) ¤

Wurzel

Suchen

Beweissystem der NASA

Beweissystem Isabelle

NIST Cobol Testsuite

Cephes Mathematical Library

Wiener Entwicklungsmethode

Haftungshinweis

Die Informationen auf dieser Webseite wurden nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit, noch Qualität der bereit gestellten Informationen zugesichert.

Bemerkung:

Die farbliche Syntaxdarstellung ist noch experimentell.