saveMRDI -- serialize a Macaulay2 object to MRDI JSON format

Usage:

saveMRDI x
Inputs:
- x, a thing, a Macaulay2 object to serialize (must have a save method registered via addSaveMethod)
Optional inputs:
- FileName => a string, default value null, if given, the JSON output is written to this file
- Namespace => a string, default value "Macaulay2", the namespace to use for serialization
- ToString => a Boolean value, default value true, if true, then the output is a JSON string; if false, then the output is a hash table representing the JSON structure
Outputs:
- a string or a hash table,

Description

This function serializes a Macaulay2 object into a JSON string following the MRDI file format specification. The output includes a namespace (_ns) identifying the software system and its version, a type descriptor (_type), and the data.

For parametric types such as PolynomialRing, RingElement, Ideal, and Matrix, the type descriptor includes a params field referencing the parent ring. Rings and other objects marked with UseID are assigned UUIDs so that multiple objects sharing the same ring refer to it by UUID rather than repeating its full description.

We may serialize a simple integer.

i1 : saveMRDI 5

o1 = {"_ns": {"Macaulay2": ["https://macaulay2.com", "1.26.05"]}, "_type":
     "ZZ", "data": "5"}

We can also serialize a polynomial ring element.

i2 : R = QQ[x,y,z];

i3 : f = x^2 + y*z - 3*x

      2
o3 = x  + y*z - 3x

o3 : R

i4 : saveMRDI f

o4 = {"_type": {"params": "6caf806b-9118-4741-bec7-217a71096848", "name":
     "RingElement"}, "data": [[["2", "0", "0"], ["1", "1"]], [["0", "1",
     "1"], ["1", "1"]], [["1", "0", "0"], ["-3", "1"]]], "_ns": {"Macaulay2":
     ["https://macaulay2.com", "1.26.05"]}, "_refs":
     {"6caf806b-9118-4741-bec7-217a71096848": {"_type": {"params": {"_type":
     "Ring", "data": "QQ"}, "name": "PolynomialRing"}, "data": {"variables":
     ["x", "y", "z"]}}}}

Ideals are serialized similarly.

i5 : I = ideal(x^2 - y, y^2 - z)

             2       2
o5 = ideal (x  - y, y  - z)

o5 : Ideal of R

i6 : saveMRDI I

o6 = {"_type": {"params": "6caf806b-9118-4741-bec7-217a71096848", "name":
     "Ideal"}, "data": [[[["2", "0", "0"], ["1", "1"]], [["0", "1", "0"],
     ["-1", "1"]]], [[["0", "2", "0"], ["1", "1"]], [["0", "0", "1"], ["-1",
     "1"]]]], "_ns": {"Macaulay2": ["https://macaulay2.com", "1.26.05"]},
     "_refs": {"6caf806b-9118-4741-bec7-217a71096848": {"_type": {"params":
     {"_type": "Ring", "data": "QQ"}, "name": "PolynomialRing"}, "data":
     {"variables": ["x", "y", "z"]}}}}

The output can be written directly to a file using the FileName option.

i7 : fn = temporaryFileName() | ".mrdi"

o7 = /tmp/M2-39433-0/0.mrdi

i8 : saveMRDI(f, FileName => fn)

o8 = {"_type": {"params": "6caf806b-9118-4741-bec7-217a71096848", "name":
     "RingElement"}, "data": [[["2", "0", "0"], ["1", "1"]], [["0", "1",
     "1"], ["1", "1"]], [["1", "0", "0"], ["-3", "1"]]], "_ns": {"Macaulay2":
     ["https://macaulay2.com", "1.26.05"]}, "_refs":
     {"6caf806b-9118-4741-bec7-217a71096848": {"_type": {"params": {"_type":
     "Ring", "data": "QQ"}, "name": "PolynomialRing"}, "data": {"variables":
     ["x", "y", "z"]}}}}

i9 : removeFile fn

The Namespace option selects a different namespace for serialization, such as OSCAR.

i10 : saveMRDI(5, Namespace => "Oscar")

o10 = {"_ns": {"Oscar": ["https://github.com/oscar-system/Oscar.jl",
      "1.6.0"]}, "_type": {"params": {"_type": "ZZRing"}, "name":
      "ZZRingElem"}, "data": "5"}

Setting ToString => false returns the hash table representation instead of a JSON string. This

i11 : saveMRDI(5, ToString => false)

o11 = HashTable{"_ns" => HashTable{"Macaulay2" => {https://macaulay2.com, 1.26.05}}}
                "_type" => ZZ
                "data" => 5

o11 : HashTable

To see which types have built-in save methods for a given namespace, call methods as follows.

i12 : methods {"Macaulay2", saveMRDI}

o12 = {0 => ({Macaulay2, saveMRDI}, ZZ)            }
      {1 => ({Macaulay2, saveMRDI}, RingElement)   }
      {2 => ({Macaulay2, saveMRDI}, Ring)          }
      {3 => ({Macaulay2, saveMRDI}, Matrix)        }
      {4 => ({Macaulay2, saveMRDI}, GaloisField)   }
      {5 => ({Macaulay2, saveMRDI}, Ideal)         }
      {6 => ({Macaulay2, saveMRDI}, PolynomialRing)}
      {7 => ({Macaulay2, saveMRDI}, QuotientRing)  }

o12 : NumberedVerticalList

i13 : methods {"Oscar", saveMRDI}

o13 = {0 => ({Oscar, saveMRDI}, QQ)            }
      {1 => ({Oscar, saveMRDI}, ZZ)            }
      {2 => ({Oscar, saveMRDI}, PolynomialRing)}
      {3 => ({Oscar, saveMRDI}, RingElement)   }
      {4 => ({Oscar, saveMRDI}, Ring)          }

o13 : NumberedVerticalList

Additional types can be supported by calling addSaveMethod.

Caveat

Not all Macaulay2 types have save methods defined. Attempting to serialize an unsupported type will produce an error. Quotient rings other than finite prime fields are not yet supported.

Ways to use saveMRDI:

saveMRDI(Thing)

For the programmer

The object saveMRDI is a method function with a single argument.

The source of this document is in /build/reproducible-path/macaulay2-1.26.05+ds/M2/Macaulay2/packages/MRDI.m2:577:0.

saveMRDI -- serialize a Macaulay2 object to MRDI JSON format

Description

Caveat

See also

Menu

Ways to use saveMRDI:

For the programmer