Saving and loading simplicial complexes

There are lots of standard formats for networks, but none (as far as I know) for simplicial complexes. In the absence of a standard, simplicial uses the most portable storage format, which would be JSON. We may add new formats if required, since JSON isn’t very efficient especially for large complexes.

File I/O

The basic functions read and write JSON-encoded complexes.

simplicial.file.read_json(path)

Read a complex in JSON format from the name file.

Parameters

path (str) – the file to read

Return type

Union[SimplicialComplex, Any]

Returns

a complex

simplicial.file.write_json(c, path)

Write a complex in JSON format to the named file.

Parameters

Conversion routines

For special cases, the raw conversion routines are also available.

simplicial.file.as_json(c)

Return a JSON string representation of a simplicial complex.

Parameters

c (SimplicialComplex) – the complex

Return type

str

Returns

a JSON representation of the complex

simplicial.file.as_simplicial_complex(o)

Decode a given dict as a simplicial complex. The most common usage for this function is as an object hook in the json.loads() and json.load() methods, for example:

json.load(fp, object_hook=simplicial.as_simplicial_complex)
Parameters

o (Any) – the dict

Return type

Union[SimplicialComplex, Any]

Returns

a simplicial complex

Encoding

class simplicial.file.JSONSimplicialComplexEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

JSON is a portable format for exchanging simplicial complexes. The encoding represents the complex as a JSON object consistting of three top-level fields:

  • “__simplicialcomplex__”: a type marker, always True

  • “__version__”: the JSON encoding version in use

  • “simplices”: a list of simplices

Each entry in the “simplices” list is a simplex, with simplices appearing in ascending order (0-simplices followed by 1-simplices and so forth). Note that this implices that, for any simplex, its faces (if any) will already have been encountered.

Each simplex is a JSON object with three fields:

  • “id”: the unique identifier of the simplex

  • “faces”: a list of the names of the faces of the simplex

  • “attributes”: a JSON object reprsenting the attributes hash of the simplex

Note that because of the restrictions of JSON the encoding of attributes may not preserve their (Python) types. In particular, Python tuples will become JSON arrays, and will be reconstructed as such when the complex is read back in.