Initial commit

.gitignore

@@ -0,0 +1,149 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Emacs
+.dir-locals.el
+.dir-locals.el~
+
+# PyCharm
+.idea/
+
+# Mac OS
+.DS_Store
+
+# Stored Trees, Dominions, and Homomorphisms
+Tree0/
+Tree1/
+Tree2/
+Tree3/
+test2.py
+
+# Stored trees and dominions
+output/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Charlotte Aten
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,80 @@
+# Discrete neural nets
+This repository contains code and examples of implementing the notion of a
+discrete neural net and polymorphic learning in Python. For more information on
+these notions, see
+[the corresponding preprint](https://arxiv.org/abs/2308.00677) on the arXiv.
+
+### Project structure
+The scripts that define basic components of the system are in the `src` folder.
+These are:
+
+* `arithmetic_operations.py`: Definitions of arithmetic operations modulo some
+    positive integer. These are used to test the basic functionality of the
+    `NeuralNet` class.
+* `dominion.py`: Tools for creating dominions, a combinatorial object used in
+    the definition of the dominion polymorphisms in `polymorphisms.py`.
+* `dominion_setup.py`: Utilities for creating files of trees, dominions with
+    those trees as constraint graphs, and the data for the corresponding
+    polymorphisms.
+* `graphs.py`: Utilities for creating and storing simple graphs, including
+    randomly-generated trees.
+* `mnist_training_binary.py`: Describes how to manufacture binary relations
+    from the MNIST dataset which can be passed as arguments into the
+    polymorphisms in `polymorphisms.py`.
+* `neural_net.py`: Definition of the `NeuralNet` class, including feeding
+    forward and learning.
+* `operations.py`: Definitions pertaining to the `Operation` class, whose
+    objects are to be thought of as operations in the sense of universal
+    algebra/model theory.
+* `polymorphisms.py`: Definitions of polymorphisms of the Hamming graph, as
+    well as a neighbor function for the learning algorithm implemented in
+    `neural_net.py`.
+* `random_neural_net.py`: Tools for making `NeuralNet` objects with
+    randomly-chosen architectures and activation functions.
+* `relations.py`: Definitions pertaining to the `Relation` class, whose objects
+    are relations in the sense of model theory.
+
+The scripts that run various tests and example applications of the system are
+in the `tests` folder. These are:
+
+* `src.py`: This script allows horizontal imports from the sibling `src`
+    folder. (That is, it adds it to the system `PATH` variable.)
+* `test_binary_relation_polymorphisms`: Examples of the basic functionality for
+    the polymorphisms defined in `polymorphisms.py` when applied to binary
+    relations.
+* `test_dominion.py`: Examples of constructing and displaying dominions as
+    defined in `dominion.py`.
+* `test_dominion_setup.py`: Create trees and dominions for use with dominion
+    polymorphisms.
+* `test_graphs.py`: Examples of creating graphs (including random trees) as
+    defined in `graphs.py`.
+* `test_mnist_training_binary.py`: Verification that MNIST training data is
+    being loaded correctly from the training dataset.
+* `test_neural_net.py`: Examples of creating `NeuralNet`s using activation
+    functions from `arithmetic_operations.py` and the `RandomOperation` from
+    `random_neural_net.py`.
+* `test_relations.py`: Examples of the basic functionality for the `Relation`s
+    defined in `relations.py`.
+
+### Environment
+This project should run on any Python3 environment without configuration. It
+assumes that there is a project folder which contains these subdirectories:
+`src` (for source code), `tests` (for tests of basic functionality and
+examples), and `output` (for output json, image files, etc.). The `output`
+folder is in the `.gitignore`, so it should not be seen on cloning. It will be
+created when a script that needs to use it is run.
+
+### TODO
+* Reincorporate the polymorphisms for the higher-arity analogues of the
+    Hamming graph which Lillian coded.
+
+### Thanks
+Thanks to all the contributors to the original incarnation of this repository:
+* Rachel Dennis
+* Hussein Khalil
+* Lillian Stolberg
+* Kevin Xue
+* Andrey Yao
+
+Thanks also to the University of Rochester and the University of Colorado
+Boulder for supporting this project.

src/arithmetic_operations.py

@@ -0,0 +1,63 @@
+"""
+Arithmetic operations for use as neural net activation functions
+"""
+from operations import Operation
+
+
+class ModularAddition(Operation):
+    """
+    Addition modulo a positive integer.
+    """
+
+    def __init__(self, order, cache_values=False):
+        """
+        Create the addition operation modulo a given positive integer.
+
+        Arguments:
+            order (int): The modulus for performing addition.
+            cache_values (bool): Whether to memoize the operation.
+        """
+
+        # Complain if the order is nonpositive.
+        assert order > 0 
+        Operation.__init__(self, 2, lambda *x: (x[0] + x[1]) % order, 
+        cache_values)
+
+
+class ModularMultiplication(Operation):
+    """
+    Multiplication modulo a positive integer.
+    """
+
+    def __init__(self, order, cache_values=False):
+        """
+        Create the multiplication operation modulo a given positive integer.
+
+        Arguments:
+            order (int): The modulus for performing multiplication.
+            cache_values (bool): Whether to memoize the operation.
+        """
+
+        # Complain if the order is nonpositive.
+        assert order > 0 
+        Operation.__init__(self, 2, lambda *x: (x[0] * x[1]) % order, 
+        cache_values)
+
+
+class ModularNegation(Operation):
+    """
+    Negation modulo a positive integer.
+    """
+
+    def __init__(self, order, cache_values=False):
+        """
+        Create the negation operation modulo a given positive integer.
+
+        Arguments:
+            order (int): The modulus for performing negation.
+            cache_values (bool): Whether to memoize the operation.
+        """
+
+        # Complain if the order is nonpositive.
+        assert order > 0
+        Operation.__init__(self, 1, lambda *x: (-x) % order, cache_values)

src/dominion.py

@@ -0,0 +1,150 @@
+"""
+Dominion
+
+Tools for creating 2-dimensional dominions
+"""
+import random, pathlib
+from matplotlib import pyplot as plt
+import output
+
+
+class Dominion:
+    """
+    A dominion, which is a square array of entries with the property that every
+    2 by 2 subarray has at most two distinct entries. Higher-dimensional
+    analogues may be implemented in the future.
+
+    Attributes:
+        labels (frozenset): The labels which may appear as entries in the
+            dominion.
+        array (tuple of tuple): The array of entries belonging to the dominion.
+    """
+
+    def __init__(self, labels, array):
+        """
+        Create a dominion with a given array of labels.
+
+        Argument:
+            labels (iterable): The labels which may appear as entries in the
+                dominion.
+            array (iterable of iterable): The array of entries belonging to the
+                dominion.
+        """
+
+        self.labels = frozenset(labels)
+        self.array = tuple(tuple(row) for row in array)
+
+    def show(self):
+        """
+        Display a textual representation of the dominion in question.
+        """
+
+        for row in self.array:
+            print(row)
+
+    def __repr__(self):
+        return "A Dominion of size {} with {} possible labels.".format(
+        len(self.array), len(self.labels))
+
+    def __str__(self):
+        labels = '{' + ', '.join(map(str, self.labels)) + '}'
+        return "A Dominion of size {} with labels from {}.".format(
+        len(self.array), labels)
+
+    def draw(self, color_map, filename):
+        """
+        Render an image from a given dominion and color map.
+
+        Arguments:
+            color_map (string): The name of a color map.
+            filename (string): The name of the resulting file.
+        """
+
+        plt.imsave(output.path + '//{}.png'.format(filename), \
+        self.array, cmap=color_map)
+
+
+def new_row(row, labels, constraint_graph=None):
+    """
+    Construct a new row for a dominion with a given collection of labels and a
+    graph constraining which labels can appear together.
+
+    Arguments:
+        row (tuple): A tuple of labels representing a row of a dominion.
+        labels (iterable): The pixel labels used in the dominion. The entries
+            of `row` should come from this.
+        constraint_graph (Graph): The graph determining which labels can appear
+            next to each other. The vertices of `constraint_graph` should be
+            the entries of `labels`. The default value `None` behaves as though
+            the graph is the complete graph on the vertex set whose members are
+            the entries of `labels'.
+    Returns:
+        tuple: A new row which is permitted to follow `row` in a dominion with
+            the given labels and constraints.
+    """
+
+    partial_row = []
+    n = len(row)
+    for i in range(n):
+        if i == 0:
+            left_candidates = frozenset((row[0],))
+            right_candidates = frozenset((row[0], row[1]))
+        elif i == n - 1:
+            left_candidates = frozenset(
+            (row[n - 2], row[n - 1], partial_row[n - 2]))
+            right_candidates = frozenset((row[n - 1],))
+        else:
+            left_candidates = frozenset(
+            (row[i - 1], row[i], partial_row[i - 1]))
+            right_candidates = frozenset((row[i], row[i + 1]))
+        # If either side already has two candidates, we must choose from the
+        # intersection of the two sides.
+        candidates = left_candidates.intersection(right_candidates)
+        # Otherwise, it must be that both the left and right sides have only a
+        # single member. In this case, we may also choose an adjacent vertex on
+        # the constraint graph.
+        if len(left_candidates) == 1 and len(right_candidates) == 1:
+            if constraint_graph is None:
+                candidates = labels
+            else:
+                candidates = candidates.union(constraint_graph.neighbors(
+                tuple(candidates)[0]))
+        # Add a random candidate.
+        random_candidate = random.sample(list(candidates), 1)
+        partial_row += random_candidate
+    return tuple(partial_row)
+
+
+def random_dominion(size, labels, constraint_graph=None):
+    """
+    Create a random dominion given a size, collection of labels, and constraint
+    graph.
+
+    Arguments:
+        size (int): The number of rows (and columns) of the dominion.
+        labels (iterable): The pixel labels used in the dominion. The entries
+            of `row` should come from this.
+        constraint_graph (Graph): The graph determining which labels can appear
+            next to each other. The vertices of `constraint_graph` should be
+            the entries of `labels`. The default value `None` behaves as though
+            the graph is the complete graph on the vertex set whose members are
+            the entries of `labels'.
+    Returns:
+        Dominion: The randomly-generated dominion.
+    """
+
+    partial_dominion = [[random.choice(labels)]]
+    for _ in range(size - 1):
+        if constraint_graph is None:
+            new_label = random.choice(labels)
+        else:
+            new_label = random.choice(
+                tuple(constraint_graph.neighbors(
+                partial_dominion[0][-1])) + (partial_dominion[0][-1],))
+        partial_dominion[0].append(new_label)
+
+    for _ in range(size - 1):
+        next_row = new_row(partial_dominion[-1], labels, constraint_graph)
+        partial_dominion.append(next_row)
+
+    return Dominion(labels, partial_dominion)

src/dominion_setup.py

@@ -0,0 +1,102 @@
+"""
+Dominion setup
+
+Create files describing trees, dominions, and corresponding polymorphisms
+"""
+import random, json
+import output
+from graphs import random_tree, load_graph_from_file
+from dominion import random_dominion
+from relations import random_relation, random_adjacent_relation, Relation
+
+
+def grow_forest(filename, num_of_trees, num_of_vertices):
+    """
+    Add a specified number of trees to a given file.
+
+    Arguments:
+        filename (str): The name of the output file.
+        num_of_trees (int): The number of trees to be created.
+        num_of_vertices (int): How many vertices each of these trees should
+            have.
+    """
+
+    for _ in range(num_of_trees):
+        T = random_tree(range(num_of_vertices))
+        T.write_to_file(filename)
+
+
+def build_dominions(tree_filename, dominion_filename, num_of_dominions,
+    dominion_size):
+    """
+    Use the trees stored in a given file as constraint graphs for creating
+    dominions. These dominions are then stored in their own file, along with a
+    note about which tree was used to create them.
+
+    Arguments:
+        tree_filename (str): The name of the file where trees are stored.
+        dominion_filename (str): The name of the output file.
+        num_of_dominions (int): The number of dominions to be created.
+        dominion_size (int): The number of rows (and columns) of the dominions.
+    """
+
+    with open(output.path + '//{}.json'.format(tree_filename), 'r') \
+    as read_file:
+        num_of_trees = sum(1 for _ in read_file)
+    for _ in range(num_of_dominions):
+        tree_number = random.randrange(num_of_trees)
+        T = load_graph_from_file(tree_filename, tree_number)
+        D = random_dominion(dominion_size, tuple(T.vertices), T)
+        with open(output.path + '//{}.json'.format(dominion_filename), 'a') \
+        as write_file:
+            json.dump((tree_number, D.array), write_file)
+            write_file.write('\n')
+
+
+def find_homomorphisms(tree_filename, homomorphism_filename, universe_size):
+    """
+    Produce a file detailing homomorphisms from a given family of trees to a
+    given Hamming graph.
+
+    Arguments:
+        tree_filename (str): The name of the file where trees are stored.
+        homomorphism_filename (str): The name of the output file.
+        universe_size (int): The number of elements in the universe of the
+            relations to be produced.
+    """
+
+    with open(output.path + '//{}.json'.format(tree_filename), 'r') \
+    as read_file:
+        num_of_trees = sum(1 for _ in read_file)
+    for tree_number in range(num_of_trees):
+        T = load_graph_from_file(tree_filename, tree_number)
+        # Choose a root of the tree and build a list of (parent, child) node
+        # pairs.
+        unexplored_vertices = list(T.vertices)
+        next_vertices_to_check = [unexplored_vertices.pop()]
+        explored_vertices = set()
+        pairs = []
+        while unexplored_vertices:
+            next_vertex = next_vertices_to_check.pop()
+            new_neighbors = frozenset(
+            T.neighbors(next_vertex)).difference(explored_vertices)
+            for neighbor in new_neighbors:
+                pairs.append((next_vertex, neighbor))
+                unexplored_vertices.remove(neighbor)
+                next_vertices_to_check.append(neighbor)
+            explored_vertices.add(next_vertex)
+        # Create a list whose entries will become the images of each label
+        # under the homomorphism. Initialize every spot to 0.
+        homomorphism_values = len(T.vertices)*[0]
+        homomorphism_values[pairs[0][0]] = random_relation(universe_size)
+        # Starting all homomorphisms at empty relation for an experiment.
+        # homomorphism_values[pairs[0][0]] = Relation([], 28, 2)
+        for (parent, child) in pairs:
+            homomorphism_values[child] = \
+            random_adjacent_relation(homomorphism_values[parent])
+        homomorphism_values = tuple(tuple(rel.tuples)
+        for rel in homomorphism_values)
+        with open(output.path + '//{}.json'.format(homomorphism_filename),
+        'a') as write_file:
+            json.dump((tree_number, homomorphism_values), write_file)
+            write_file.write('\n')

src/graphs.py

@@ -0,0 +1,130 @@