README
¶
go-pflow
A Go library for Petri net modeling, ODE simulation, process mining, and zero-knowledge proofs.
go-pflow is not an AI/ML library. It implements structural, dynamical computation based on Petri nets and differential equations. See Why Petri Nets? for the motivation.
For comprehensive documentation, see the book.
Installation
go get github.com/pflow-xyz/go-pflow
Quick Start
// Build a Petri net and simulate with ODE solver
net, rates := petri.Build().
Place("S", 999).Place("I", 1).Place("R", 0).
Transition("infect").Transition("recover").
Arc("S", "infect", 1).Arc("I", "infect", 1).Arc("infect", "I", 2).
Arc("I", "recover", 1).Arc("recover", "R", 1).
WithCustomRates(map[string]float64{"infect": 0.3, "recover": 0.1})
prob := solver.NewProblem(net, net.SetState(nil), [2]float64{0, 100}, rates)
sol := solver.Solve(prob, solver.Tsit5(), solver.DefaultOptions())
fmt.Println("Final state:", sol.GetFinalState())
See The go-pflow Library for the full API guide.
Packages
| Package | Purpose | Book Chapter |
|---|---|---|
petri |
Core types, fluent Builder API | Ch 1: Why Petri Nets? |
solver |
ODE solvers (Tsit5, RK45, implicit) | Ch 3: Discrete to Continuous |
stochastic |
Gillespie SSA, SSA/ODE dispatch; Options{Portable: true} is byte-exact with pflow-rs, pflow-xyz and pflow-jl (goldens in stochastic/testdata/portable/, make ssa-goldens; writeup) |
Ch 3: Discrete to Continuous |
stateutil |
State map utilities | Ch 18: go-pflow Library |
hypothesis |
Move evaluation for game AI | Ch 6: Game Mechanics |
sensitivity |
Parameter sensitivity analysis | Ch 18: go-pflow Library |
cache |
Simulation memoization | Ch 18: go-pflow Library |
reachability |
Deadlock/liveness analysis, P/T-invariants, unboundedness witnesses | Ch 2: Mathematics of Flow |
verify |
Declarative property checking — proved/refuted + counterexample | Model correctness |
workflow |
Task dependencies, SLA tracking | Ch 10: Complex State Machines |
statemachine |
Hierarchical state machines | Ch 18: go-pflow Library |
actor |
Message-passing actor model | Ch 18: go-pflow Library |
eventlog |
Event log parsing | Ch 11: Process Mining |
mining |
Process discovery, rate learning | Ch 11: Process Mining |
monitoring |
Real-time prediction, SLA alerts | Ch 11: Process Mining |
learn |
ODE parameter fitting and system identification | Ch 18: go-pflow Library |
tokenmodel |
Token model schemas, DSL | Ch 4: Token Language |
tokenmodel/dataflow |
Beam-style streaming pipelines, discrete-event process simulation | — |
codegen/solidity |
Solidity smart contract generation | Ch 17: Code Generation |
prover |
Groth16 ZK proofs with gnark | Ch 12: Zero-Knowledge Proofs |
visualization |
SVG rendering | Ch 18: go-pflow Library |
plotter |
Time series SVG plots | Ch 18: go-pflow Library |
Examples
Each example maps to a book chapter demonstrating the modeling pattern:
| Example | Domain | Book Chapter | Run |
|---|---|---|---|
| basic | Token flow fundamentals | Ch 1 | cd examples/basic && go run main.go |
| coffeeshop | Resource modeling | Ch 5 | cd examples/coffeeshop/cmd && go run main.go |
| tictactoe | Game AI, move evaluation | Ch 6 | cd examples/tictactoe && go run ./cmd |
| sudoku | Constraint satisfaction | Ch 7 | cd examples/sudoku/cmd && go run *.go |
| knapsack | Combinatorial optimization | Ch 8 | cd examples/knapsack/cmd && go run *.go |
| poker | Complex state machines | Ch 10 | cd examples/poker && go run ./cmd |
| monitoring_demo | Process mining, SLA prediction | Ch 11 | cd examples/monitoring_demo && go run main.go |
| erc | Token standards, Solidity codegen | Ch 4 | go run ./examples/erc |
| connect4 | Pattern recognition | Ch 6 | cd examples/connect4 && go run ./cmd |
| nim | Optimal strategy | Ch 6 | cd examples/nim && go run ./cmd |
| chess | N-Queens, Knight's Tour | Ch 7 | cd examples/chess/cmd && go run *.go |
| neural | Parameter learning | Ch 3 | cd examples/neural && go run main.go |
| visualization_demo | SVG generation | Ch 16 | make run-visualization |
See examples/README.md for more details.
The Book
book.pflow.xyz covers everything from foundations to advanced topics:
Part I: Foundations — Why Petri Nets, Mathematics of Flow, Discrete to Continuous, Token Language
Part II: Applications — Resource Modeling, Game Mechanics, Constraint Satisfaction, Optimization, Enzyme Kinetics, Complex State Machines
Part III: Advanced — Process Mining, Zero-Knowledge Proofs, Topology-Driven Verification, Declarative Infrastructure
Part IV: Building — Visual Editor, Code Generation, go-pflow Library, Dual Implementation
Testing
go test ./...
CLI
The pflow CLI provides simulation, analysis, and plotting from the command line. See cmd/pflow/README.md.
Compatibility
- Go 1.23+
- JSON format compatible with pflow.xyz
License
MIT License - see LICENSE for details.
Related
- book.pflow.xyz — Technical book
- pflow.xyz — Visual editor and JavaScript implementation
- RESEARCH_PAPER_OUTLINE.md — Research paper draft
Directories
¶
| Path | Synopsis |
|---|---|
|
Composable form of ActorSystem on the metamodel composition layer.
|
Composable form of ActorSystem on the metamodel composition layer. |
|
Package cache provides memoization for ODE simulations.
|
Package cache provides memoization for ODE simulations. |
|
cmd
|
|
|
pflow
command
|
|
|
ssa-goldens
command
Command ssa-goldens writes the portable SSA goldens — stochastic/testdata/portable/<name>.json — that pflow-rs, pflow-xyz and pflow-jl replay byte for byte.
|
Command ssa-goldens writes the portable SSA goldens — stochastic/testdata/portable/<name>.json — that pflow-rs, pflow-xyz and pflow-jl replay byte for byte. |
|
zk-field-parity
command
Command zk-field-parity emits a deterministic digest of BN254 field arithmetic and gnark circuit artifacts.
|
Command zk-field-parity emits a deterministic digest of BN254 field arithmetic and gnark circuit artifacts. |
|
codegen
|
|
|
solidity
Package solidity generates Solidity smart contracts from token model schemas.
|
Package solidity generates Solidity smart contracts from token model schemas. |
|
Package compat bridges the two Petri implementations in this repo so facades built on either side can interoperate during migration.
|
Package compat bridges the two Petri implementations in this repo so facades built on either side can interoperate during migration. |
|
Package derive builds evaluation variants of a declared Petri net.
|
Package derive builds evaluation variants of a declared Petri net. |
|
Package engine provides a state machine harness for continuous Petri net simulation.
|
Package engine provides a state machine harness for continuous Petri net simulation. |
|
Package eventlog provides parsing and analysis of process event logs.
|
Package eventlog provides parsing and analysis of process event logs. |
|
Package eventsource provides event sourcing infrastructure for CQRS applications.
|
Package eventsource provides event sourcing infrastructure for CQRS applications. |
|
examples
|
|
|
basic
command
|
|
|
chess/cmd
command
|
|
|
coffeeshop
Package coffeeshop demonstrates a fully automated coffee shop using go-pflow.
|
Package coffeeshop demonstrates a fully automated coffee shop using go-pflow. |
|
coffeeshop/cmd
command
Coffee Shop Automation Demo
|
Coffee Shop Automation Demo |
|
coffeeshop/cmd/sim
command
Coffee Shop Simulator CLI
|
Coffee Shop Simulator CLI |
|
coffeeshop/dataflow
Package dataflow expresses the coffeeshop simulation as an Apache Beam / Cloud Dataflow style multi-stage pipeline whose internals lower to a subnet bundle of tokenmodel/petri nets.
|
Package dataflow expresses the coffeeshop simulation as an Apache Beam / Cloud Dataflow style multi-stage pipeline whose internals lower to a subnet bundle of tokenmodel/petri nets. |
|
coffeeshop/dataflow/cmd
command
Demo: coffeeshop expressed as a Beam-style Dataflow pipeline whose internals are tokenmodel/petri subnets.
|
Demo: coffeeshop expressed as a Beam-style Dataflow pipeline whose internals are tokenmodel/petri subnets. |
|
connect4/cmd
command
|
|
|
erc
command
Package main demonstrates defining ERC token standards as Petri net schemas and generating Solidity contracts from them.
|
Package main demonstrates defining ERC token standards as Petri net schemas and generating Solidity contracts from them. |
|
eventlog_demo
command
|
|
|
f91w
Package f91w provides a Petri net simulation of the Casio F-91W digital watch.
|
Package f91w provides a Petri net simulation of the Casio F-91W digital watch. |
|
f91w/cmd
command
Casio F-91W Watch Simulator Based on the XState machine from https://github.com/dundalek/casio-f91w-fsm
|
Casio F-91W Watch Simulator Based on the XState machine from https://github.com/dundalek/casio-f91w-fsm |
|
incident_simulator
command
|
|
|
knapsack/cmd
command
|
|
|
mining_demo
command
|
|
|
monitoring_demo
command
|
|
|
neural/cmd/demo
command
|
|
|
neural/cmd/main
command
|
|
|
neural/cmd/reverse
command
|
|
|
nim/cmd
command
|
|
|
poker/cmd
command
|
|
|
stoplight
command
|
|
|
sudoku/cmd
command
|
|
|
tictactoe/cmd
command
|
|
|
tictactoe/metamodel
Package metamodel demonstrates the struct tag DSL for Tic-tac-toe.
|
Package metamodel demonstrates the struct tag DSL for Tic-tac-toe. |
|
trafficlight
command
|
|
|
visualization_demo
command
Visualization demo - generates example SVG files for workflows and state machines
|
Visualization demo - generates example SVG files for workflows and state machines |
|
Package graphql provides a GraphQL server for Petri net models.
|
Package graphql provides a GraphQL server for Petri net models. |
|
example
command
Example GraphQL server for Petri net models.
|
Example GraphQL server for Petri net models. |
|
Package hypothesis provides utilities for evaluating hypothetical states via ODE simulation.
|
Package hypothesis provides utilities for evaluating hypothetical states via ODE simulation. |
|
Package learn fits the unknown parameters of continuous Petri-net models to observed data — mechanistic system identification.
|
Package learn fits the unknown parameters of continuous Petri-net models to observed data — mechanistic system identification. |
|
Package metamodel provides compatibility utilities for migrating from the legacy Model type to the modern generic PetriNet types.
|
Package metamodel provides compatibility utilities for migrating from the legacy Model type to the modern generic PetriNet types. |
|
metapetri
Package metapetri is the bridge from a metamodel.Model to the petri.PetriNet that reachability, invariants and verify consume.
|
Package metapetri is the bridge from a metamodel.Model to the petri.PetriNet that reachability, invariants and verify consume. |
|
Package mining provides process mining algorithms including discovery and conformance checking.
|
Package mining provides process mining algorithms including discovery and conformance checking. |
|
Package monitoring provides real-time predictive process monitoring.
|
Package monitoring provides real-time predictive process monitoring. |
|
Package parser handles JSON import/export for Petri nets.
|
Package parser handles JSON import/export for Petri nets. |
|
Package petri implements core Petri net data structures.
|
Package petri implements core Petri net data structures. |
|
Package plotter provides SVG visualization for ODE solutions.
|
Package plotter provides SVG visualization for ODE solutions. |
|
Package reachability provides state space analysis for Petri nets.
|
Package reachability provides state space analysis for Petri nets. |
|
Package results defines the structured output format for simulations
|
Package results defines the structured output format for simulations |
|
Package sensitivity provides tools for analyzing how Petri net behavior changes with different parameters.
|
Package sensitivity provides tools for analyzing how Petri net behavior changes with different parameters. |
|
Package solver implements ODE (Ordinary Differential Equation) solvers for Petri net simulation using mass-action kinetics.
|
Package solver implements ODE (Ordinary Differential Equation) solvers for Petri net simulation using mass-action kinetics. |
|
Composable form of Chart on the metamodel composition layer.
|
Composable form of Chart on the metamodel composition layer. |
|
Package stateutil provides utility functions for manipulating Petri net state maps.
|
Package stateutil provides utility functions for manipulating Petri net state maps. |
|
Package stochastic simulates a metamodel.Model as a continuous-time Markov chain (Gillespie's direct method) and dispatches the same declared net to either that engine or the mass-action ODE in solver — Petri.jl's ODEProblem/JumpProblem choice, off one structure.
|
Package stochastic simulates a metamodel.Model as a continuous-time Markov chain (Gillespie's direct method) and dispatches the same declared net to either that engine or the mass-action ODE in solver — Petri.jl's ODEProblem/JumpProblem choice, off one structure. |
|
Package templates provides common Petri net patterns
|
Package templates provides common Petri net patterns |
|
Package tokenmodel defines abstract building blocks for formal models.
|
Package tokenmodel defines abstract building blocks for formal models. |
|
dataflow
Beam-style fluent source chaining.
|
Beam-style fluent source chaining. |
|
dataflow/transport
Package transport is the L3.1 wire layer for subnet.Bundle execution.
|
Package transport is the L3.1 wire layer for subnet.Bundle execution. |
|
dsl
Package dsl implements an S-expression DSL for defining token model schemas.
|
Package dsl implements an S-expression DSL for defining token model schemas. |
|
guard
Package guard implements a secure guard expression evaluator for Petri net transitions.
|
Package guard implements a secure guard expression evaluator for Petri net transitions. |
|
petri
Package petri provides structural analysis for Petri net invariant proofs.
|
Package petri provides structural analysis for Petri net invariant proofs. |
|
subnet
Graphviz DOT rendering for Bundles.
|
Graphviz DOT rendering for Bundles. |
|
windowing
Package windowing scaffolds Apache Beam-style streaming windowing as a modeled feature over tokenmodel/petri.
|
Package windowing scaffolds Apache Beam-style streaming windowing as a modeled feature over tokenmodel/petri. |
|
Package validation provides structural analysis and validation for Petri nets
|
Package validation provides structural analysis and validation for Petri nets |
|
Package verify turns questions about a Petri net into verdicts with evidence.
|
Package verify turns questions about a Petri net into verdicts with evidence. |
|
Package visualization provides utilities for visualizing Petri nets as SVG.
|
Package visualization provides utilities for visualizing Petri nets as SVG. |
|
Composable form of Workflow on the metamodel composition layer.
|
Composable form of Workflow on the metamodel composition layer. |
|
Package zkcompile transforms Petri net models into ZK circuit constraints.
|
Package zkcompile transforms Petri net models into ZK circuit constraints. |
|
petrigen
Package petrigen generates gnark ZK circuits from Petri net models.
|
Package petrigen generates gnark ZK circuits from Petri net models. |
Click to show internal directories.
Click to hide internal directories.