constrainthg 0.2.3

Kernel for building and simulating constraint hypergraphs.

ConstraintHg is a systems modeling kernel written in Python that enables general definition and universal simulation of any system. The kernel breaks a system down into the informational values (nodes) and functional relationships (hyperedges), providing robust simulation through pathfinding operations. This repository is under active development (no official release yet), and is therefore subject to change without warning. It is not a rigorous data storage solution. Do not use this as a database.

Uses

ConstraintHg enables the following functionalities:

• Universal systems modeling: any model can be represented as a Constraint Hypergraph, meaning that models of different types and sources can be combined inside a single hypergraph.
• Universal simulation: Any simulation that could be conducted on a systems model can be discovered by ConstraintHg, or in other words, a program for calculating any piece of information (given a set of inputs) can be compiled for any system--given that such a program exists!
• System interrogation: Any system can be turned into a black box where information is autonomously returned by ConstraintHg--whether that information was recorded or simulated. This is especially useful for automatons trying to interface with a system.
• Digital twin representation: Modeling a real systsem with ConstraintHg is equivalent to creating a digital twin of that system, providing universal observation of the properties and biconnectiviy with the modeled system.

Links and More Information

• Homepage: Link
• Learn to use: Get Started
• Learn about Constraint Hypergraphs: Resources
• API Documentation: Read the Docs
• Video overview: YouTube
• Papers:
  • Introduction of Constraint Hypergraphs

Licensing and Usage

Author: John Morris
Contact: Reach out to my GitHub profile (jmorris335)
Usage: Released under the Apache 2.0 license. This permissive license allows you can use, modify, and distribute this source code as desired (official terms are in the LICENSE file). The main limitations are that you'll need to include a copy of this license as well as the NOTICE file, and you'll have to state your changes. We'd appreciate hearing if you used this for something helpful. Let us know by contacting us via our profiles!

Install

ConstraintHg is listed on the Python Package Index. To install, paste the following to your command terminal:

   pip install constrainthg

Introduction

Hypergraphs are normal graphs but without the constraint that edges must only link between two nodes. Because of this expanded generality, hypergraphs can be used to model more complex relationships. For instance, the relationship A + B = C is a multinodal relationship between three nodes, A, B, and C. You can think of all three nodes being linked by a 2D hyperedge, so that to move along that hyperedge you need at least two of three nodes.

A constraint hypergraph is a hypergraph where the relationships are constraints that can be solved for by some execution engine, generally via API calls. These constraints reveal the behavior of the system. The goal is for the hypergraph to be platform agnostic, while API calls allow for edges to be processed on any available software.

Processing a series of nodes and edges (a "route") is what constitutes a simulation, so one of the uses of an constraint hypergraph is enabling high-level simulation ability from any possible entry point in a system model.

Getting started

Note that this demo is found in demos/demo_basic.py Let's build a basic constraint hypergraph of the following equations:

• $A + B = C$
• $A = -D$
• $B = -E$
• $D + E = F$
• $F = -C$

First, import the classes.

from constrainthg.hypergraph import Hypergraph
import constrainthg.relations as R

A hypergraph consists of edges that map between a set of nodes to a single node. We provide the mapping by defining a constraint function (many of which are already defined in the relationships module). The two relationships defined in the governing equations are addition and negation. Using the typical syntax, we refer to the functions defined in relationships with R.<name>, in this case R.Rsum and R.Rnegate. To make the hypergraph we'll need to compose the 5 edges (equations) given above.

hg = Hypergraph()
hg.add_edge(['A', 'B'], 'C', R.Rsum)
hg.add_edge('A', 'D', R.Rnegate)
hg.add_edge('B', 'E', R.Rnegate)
hg.add_edge(['D', 'E'], 'F', R.Rsum)
hg.add_edge('F', 'C', R.Rnegate)

We can verify that the hypergraph was made correctly by tracing all possible paths for generating C using the printPaths function.

print(hg.print_paths('C'))

This should give us the following output. Hyperedges are indicated with a ◯, with the last source separated from other edges with a ●.

└──C, cost=1
   ├◯─A, cost=0
   ├●─B, cost=0
   └──F, cost=3
      ├◯─D, cost=1
      │  └──A, cost=0
      └●─E, cost=1
         └──B, cost=0

Compute the value of $C$ by picking a set of source nodes (inputs), such as $A$ and $B$ or $A$ and $E$. Set values for the inputs and the solver will automatically calulate an optimized route to simulate $C$.

print("**Inputs A and E**")
hg.solve('C', {'A':3, 'E':-7}, to_print=True)
print("**Inputs A and B**")
hg.solve('C', {'A':3, 'B':7}, to_print=True)

The output of the above should be:

**Inputs A and E**
└──C= 10, cost=3
   └──F= -10, cost=2
      ├──D= -3, cost=1
      │  └──A= 3, cost=0
      └──E= -7, cost=0

**Inputs A and B**
└──C= 10, cost=1
   ├──A= 3, cost=0
   └──B= 7, cost=0

Examples

Many examples are available in the demos directory. These, and other external examples include:

• Pendulum: demonstrating model selection
• Elevator: combining discrete-event simulation with a PID controller
• Naval Microgrid: complex system featuring data querying and dynamic simulation and linear systems
• Crankshaft: integrates CAD software (Onshape) with dynamic simulation