acsets.acsets

In this module, we define schemas and acsets.

class HashableBaseModel(**data)

An extension of BaseModel with an implementation of __hash__

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

__init__ uses __pydantic_self__ instead of the more common self for the first arg to allow self as a field name.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

class Ob(**data)

This class represents objects in schemas. In an acset, there is a table for each object in the schema.

For instance, in the schema for graphs, there are two objects, Ob(“V”) and Ob(“E”) for the tables of vertices and edges, respectively

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

__init__ uses __pydantic_self__ instead of the more common self for the first arg to allow self as a field name.

class Config

pydantic config

model_config: ClassVar[ConfigDict] = {'allow_mutation': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'description': FieldInfo(annotation=Union[str, NoneType], required=False, description='A long-form description of the object'), 'name': FieldInfo(annotation=str, required=True, description='The name of the object'), 'title': FieldInfo(annotation=Union[str, NoneType], required=False, description='The human-readable label for the object')}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

class Hom(**data)

This class represents morphisms in schemas. In an acset, the table corresponding to an object x has a foreign key column for every morphism in the schema that has a domain (dom) of x, that has ids that reference rows in the table for the codomain (codom).

For instance, in the schema for graphs, there are two morphisms Hom(“src”, E, V) and Hom(“tgt”, E, V).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

__init__ uses __pydantic_self__ instead of the more common self for the first arg to allow self as a field name.

classmethod dom_string(ob)

Validate domain inputs to string

Args:

ob: either a string of the object name or the object

Returns:

the string representation of the object

classmethod codom_string(ob)

Validate codomain inputs to string

Args:

ob: either a string of the object name or the object

Returns:

the string representation of the object

class Config

pydantic config

model_config: ClassVar[ConfigDict] = {'allow_mutation': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'codom': FieldInfo(annotation=str, required=True, title='codomain', description='The object of the codomain.'), 'description': FieldInfo(annotation=Union[str, NoneType], required=False, description='A long-form description of the morphism'), 'dom': FieldInfo(annotation=str, required=True, title='domain', description='The object of the domain.'), 'name': FieldInfo(annotation=str, required=True, description='The name of the morphism.'), 'title': FieldInfo(annotation=Union[str, NoneType], required=False, description='The human-readable label for the morphism')}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

class AttrType(**data)

This class represents attribute types in schemas. An attribute type is the “codomain” of attributes. In an acset, each attrtype is associated with a type. But in general, acsets are “polymorphic” over the types of their attributes.

For instance, in the schema for Petri nets, there is an attribute type Name = AttrType(“Name”). Typically, we might associate this to the type str, for single names. However, we might also want a Petri net where each transition, for instance, has a tuple of strings as its name.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

__init__ uses __pydantic_self__ instead of the more common self for the first arg to allow self as a field name.

classmethod evaluate_type(ty)

Populate the parsed value of the type.

class Config

pydantic config

model_config: ClassVar[ConfigDict] = {'allow_mutation': False, 'json_encoders': {<class 'type'>: <function AttrType.Config.<lambda>>}}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'description': FieldInfo(annotation=Union[str, NoneType], required=False), 'name': FieldInfo(annotation=str, required=True, description='The name of the attribute type.'), 'title': FieldInfo(annotation=Union[str, NoneType], required=False), 'ty': FieldInfo(annotation=type, required=True, description='The type assigned to the attribute type. Use a string referring to the Python type')}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

class Attr(**data)

This class represents attributes in schemas. An attribute corresponds to a non-foreign-key column in the table for its domain (dom).

For instance, in the schema for Petri nets, we have Attr(“sname”, Species, Name) which is the attribute that stores the name of a species in a Petri net.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

__init__ uses __pydantic_self__ instead of the more common self for the first arg to allow self as a field name.

classmethod dom_string(ob)

Validate domain inputs to string

Args:

ob: either a string of the object name or the object

Returns:

the string representation of the object

classmethod codom_string(at)

Validate codomain inputs to string

Args:

ob: either a string of the AttrType name or the AttrType object

Returns:

the string representation of the AttrType

class Config

pydantic config

model_config: ClassVar[ConfigDict] = {'allow_mutation': False, 'json_encoders': {<class 'type'>: <function Attr.Config.<lambda>>}}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'codom': FieldInfo(annotation=str, required=True, title='codomain', description='The attribute type in the codomain'), 'description': FieldInfo(annotation=Union[str, NoneType], required=False), 'dom': FieldInfo(annotation=str, required=True, title='domain', description='The object in the domain.'), 'name': FieldInfo(annotation=str, required=True, title='name', description='The name of the attribute.'), 'title': FieldInfo(annotation=Union[str, NoneType], required=False)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

class VersionSpec(**data)

We use this version spec to version the serialization format, so that if we change the serialization format, we can migrate old serializations into new ones.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

__init__ uses __pydantic_self__ instead of the more common self for the first arg to allow self as a field name.

class Config

pydantic config

model_config: ClassVar[ConfigDict] = {'allow_mutation': False}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'ACSetSchema': FieldInfo(annotation=str, required=True), 'Catlab': FieldInfo(annotation=str, required=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

class CatlabSchema(**data)

This schema is carefully laid out so that the JSON produced/consumed will be compatible with Catlab schemas. However, the user should not use this; instead the user should use the Schema class, which is below.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

__init__ uses __pydantic_self__ instead of the more common self for the first arg to allow self as a field name.

class Config

pydantic config

model_config: ClassVar[ConfigDict] = {'allow_mutation': False, 'json_encoders': {<class 'type'>: <function CatlabSchema.Config.<lambda>>}}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'Attr': FieldInfo(annotation=list[Attr], required=True), 'AttrType': FieldInfo(annotation=list[AttrType], required=True), 'Hom': FieldInfo(annotation=list[Hom], required=True), 'Ob': FieldInfo(annotation=list[Ob], required=True), 'version': FieldInfo(annotation=VersionSpec, required=False, default=VersionSpec(ACSetSchema='0.0.1', Catlab='0.14.12'))}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

class Schema(name, obs, homs, attrtypes, attrs)

This is a schema for an acset. Every acset needs a schema, to restrict the allowed operations to ensure consistency.

Initialize a schema object.

Args:

name: The name of the schema. obs: A list of of objects (Ob). homs: A list of morphisms (Hom). attrtypes: A list of attribute types (AttrType). attrs: A list of attributes (Attr).

valtype(prop)

Resolve the python type of a given property

Args:

prop: Either a Hom object or a AttrTyp object

Returns:

The Property value type

valid_value(prop, val)

Verify if a given value is valid for a given property

Args:

val (any): the value to check if valid prop: the Property object

Returns:

true if the value is valid for the given property, false otherwise

classmethod from_catlab(name, catlab_schema)

Get a schema from a CatLab schema.

Return type:

Schema

make_schema(uri=None)

Make a JSON schema dictionary object representing this schema.

Parameters:

uri (Optional[str]) – The URI where the JSON file that corresponds to this schema lives

Returns:

A dictionary with the JSON schema inside it that can be written with json.dump().

write_schema(path, uri=None)

Write a JSON schema to a file path.

Return type:

None

property obs

Get the objects of the schema

Returns:

A list of of Obs

property homs

Get the morphisms of the schema

Returns:

A list of of Homs

property attrtypes

Get the attribute types of the schema

Returns:

A list of of AttrTypes

property attrs

Get the attributes of the schema

Returns:

A list of of Attrs

props_outof(ob)

Get all of the properties with the domain of ob in the schema.

Return type:

list[Union[Hom, Attr]]

Args:

ob: An Ob object that is in the schema.

Returns:

A list of Hom and Attr objects where ob is in the domain of the properties.

homs_outof(ob)

Get all of the morphisms that the given object ob maps to in the schema.

Return type:

list[Union[Hom, Attr]]

Args:

ob: An Ob object that is in the schema.

Returns:

A list of Hom objects where ob is in the domain of the morphism.

attrs_outof(ob)

Get all of the attributes that the given object ob maps to in the schema.

Return type:

list[Union[Hom, Attr]]

Args:

ob: An Ob object that is in the schema.

Returns:

A list of Attr objects where ob is in the domain of the attribute.

from_string(s)

Get the appropriate object, morphism, attribute type, or attribute from the schema by name.

Args:

s: The name of the schema element that you want to retrieve.

Returns:

The Ob/Hom/AttrType/Attr object that has the name s or None if no names match.

class ACSet(name, schema)

An acset consists of a collection of tables, one for every object in the schema.

The rows of the tables are called “parts”, and the cells of the rows are called “subparts”.

One can get all of the parts corresponding to an object, add parts, get the subparts, and set the subparts. Removing parts is currently unsupported.

Initialize a new ACSet.

Args:

name: The name of the ACSset. schema: The schema of the ACSet.

classmethod from_obj(*, name, obj)

Make an ACSet from a JSON object representing its schema.

Parameters:

• name (str) – The name of the acset

• obj – A JSON object representing the acset, to be loaded through CatlabSchema

Return type:

ACSet

Returns:

An acset object

You can get an example ACSets schema definition from the testing suite and load it over the web with the following code:

import requests

url = "https://github.com/AlgebraicJulia/py-acsets/blob/main/tests/petri_schema.json"
obj = requests.get(url).json()
sir = ACSet.from_obj(name="petri", obj=obj)
s, i, r = sir.add_parts("S", 3)

classmethod from_file(*, name, path)

Make an ACSet from a file with the JSON representing its schema.

Parameters:

• name (str) – The name of the acset

• path (PathLike) – A path to the file

Return type:

ACSet

Returns:

An acset object

For example, if you have a JSON file representing the Petri Net schema, you can load it and start working with:

path = ...
sir = ACSet.from_file(name="petri", path=path)
s, i, r = sir.add_parts("S", 3)

add_parts(ob, n)

Add n parts to an object in the ACset.

Return type:

range

Args:

ob: The object in the ACSet to add parts to. n: The number of parts to be added.

Returns:

A range of the indexes of the new parts added to the object.

add_part(ob)

Add a single part to an object in the ACSet

Return type:

int

Args:

ob: The object in the ACSet to add a part to.

Returns:

The index of the new part added to the object.

set_subpart(i, f, x)

Modify a morphism or attribute for a row in a table of the ACSet.

Args:

i: The row index for the property mapping to be added to. f: The Hom or Attr to modify. x: A valid type for the given Hom or Attr to set the value or None to delete the property.

has_subpart(i, f)

Check if a property exists for a given row in a table of the ACSset.

Args:

i: The row index for the property mapping to be added to. f: The Hom or Attr to check for.

Returns:

True if the property f exists on row i or False if it doesn’t.

subpart(i, f, oneindex=False)

Get the subpart of a part in an ACSet

Args:

oneindex (boolean): Whether or not to return the index starting at 1 or 0, default is False which is zero-indexed i: The part that you are indexing. f: The Hom or Attr to retrieve.

Returns:

The subpart of the ACset.

nparts(ob)

Get the number of rows in a given table of the ACSet.

Return type:

int

Args:

ob: The object in the ACSet.

Returns:

The number of rows in ob.

parts(ob)

Get all of the row indexes in a given table of the ACSet.

Return type:

range

Args:

ob: The object in the ACSet.

Returns:

The range of all of the rows in ob.

incident(x, f)

Get all of the subparts incident to a part in the ACset.

Return type:

list[int]

Args:

x: The subpart to look for. f: The Hom or Attr mapping to search.

Returns:

A list indexes.

prop_dict(ob, i)

Get a dictionary of all subparts for a given row in a table.

Return type:

dict[str, Any]

Args:

ob: The object in the ACSet to index. i: The row in ob.

Returns:

A dictionary mapping property name to the value

export_pydantic()

Serialize the ACSet to a pydantic model.

Returns:

The pydantic model of the serialized ACSet.

classmethod import_pydantic(name, schema, d)

Deserialize a pydantic model to an ACSet with a given Schema

Args:

schema: The Schema of the ACSet that is defined by the pydantic model. d: The pydantic model object.

Returns:

The deserialized ACSet object.

to_json_obj()

Serialize the ACSet to a JSON object.

Returns:

The JSON object of the serialized ACSet.

to_json_file(fname, *args, **kwargs)

Serialize the ACSet to a JSON file.

Args:

fname: The file name to write the JSON to.

to_json_str(*args, **kwargs)

Serialize the ACSet to a JSON string.

Returns:

The JSON string of the serialized ACSet.

classmethod read_json(name, schema, s)

Deserialize a JSON string to an ACSet with a given Schema.

Args:

name: The name of the ACSset. schema: The Schema of the ACSet that is defined in the given JSON. s: The JSON string

Returns:

The deserialized ACSet object.