home / skills / plurigrid / asi / structured-decompositions-jl

structured-decompositions-jl skill

safe

This skill helps you work with StructuredDecompositions.jl by building, inspecting, and lifting functors over decompositions to solve sheaf-based decisions.

npx playbooks add skill plurigrid/asi --skill structured-decompositions-jl

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

2.1 KB

---
name: structured-decompositions-jl
description: Use when users ask about StructuredDecompositions.jl, structured decompositions,
  or sheaf-based decision problems (AlgebraicJulia/Catlab).
---

# StructuredDecompositions.jl

You help with Julia tasks involving StructuredDecompositions.jl. Prefer precise, minimal examples and reuse the package's existing API rather than inventing new abstractions.

## Quick start
- `using StructuredDecompositions`
- Build a decomposition from a graph: `d = StrDecomp(graph)` (optional `alg` and `snd` keywords).
- Build from a shape + diagram: `d = StrDecomp(shape, diagram, Decomposition)` or `CoDecomposition`.
- Inspect: `bags(d)`, `adhesions(d)`, `adhesionSpans(d)` (pass `true` for indexed pairs).
- Lift a functor: use the bold-D function (type `\mathbf{D}` then Tab in Julia) with signature `D(f, d, t::DecompType = d.decomp_type)`.
- Decide a sheaf-encoded problem: `ok, witness = decide_sheaf_tree_shape(f, d)`.

## Guidelines
- `decide_sheaf_tree_shape` assumes FinSet-valued sheaves; if you pass a `solution_space_decomp`, ensure it is a `CoDecomposition`.
- `adhesion_filter` (not exported) errors on `Decomposition`; only use it with `CoDecomposition`.
- Use Catlab types (`Graph`, `ACSetTransformation`, `FinDomFunctor`, `FinSet`, `FinFunction`) to build diagrams.
- Prefer small, runnable snippets. If a full example is large, summarize and point to the references.
- If a task needs ACSet schema definitions or Catlab graph basics, consult `references/acsets-bridge.md` or load the `acsets-algebraic-databases` skill.

## References
- `references/overview.md` for the API map and key behaviors.
- `references/examples.md` for minimal usage sketches.
- `references/graph-coloring.md` for an ASCII-only end-to-end coloring example.
- `references/acsets-bridge.md` for ACSet/Catlab basics used by this package.

## Scripts
- `scripts/quickstart.jl` builds a simple decomposition and prints bags/adhesions.

## Example triggers
- "Make a structured decomposition for this graph."
- "Lift a functor over a decomposition and decide a sheaf."
- "How do I use decide_sheaf_tree_shape for graph coloring?"

Overview

This skill helps with Julia workflows that use StructuredDecompositions.jl to build, inspect, lift, and decide sheaf-encoded problems on decompositions. It favors minimal, runnable snippets and reuses the package API exactly as provided. The focus is on tree-shaped decompositions, CoDecomposition vs Decomposition, and FinSet-valued sheaf decision problems.

How this skill works

You construct decompositions from a Graph or from a shape + diagram using StrDecomp or StrDecomp(shape, diagram, Decomposition/CoDecomposition). The skill shows how to inspect bags, adhesions, and adhesion spans, lift functors with the bold-D function D(f, d, t), and decide FinSet sheaf problems via decide_sheaf_tree_shape. It warns about Decomposition vs CoDecomposition behaviors (e.g. adhesion_filter) and uses Catlab types for diagrams and functors.

When to use it

You need a compact, runnable example that builds a StructuredDecompositions.jl object.
You want to lift a Catlab FinSet-valued functor over a decomposition and inspect results.
You need to decide a sheaf-encoded constraint problem on a tree-shaped decomposition.
You must convert an ACSet/Catlab diagram to a decomposition and test solution spaces.
You are preparing a small demo for graph-coloring or similar combinatorial problems.

Best practices

Prefer the package API: StrDecomp(graph), StrDecomp(shape, diagram, Decomposition/CoDecomposition), bags(d), adhesions(d).
Use CoDecomposition for solution_space_decomp and any calls that require adhesion_filter.
Keep examples minimal and executable; use Catlab types (Graph, ACSetTransformation, FinDomFunctor, FinSet, FinFunction).
When lifting, call D(f, d) and explicitly pass DecompType only if needed: D(f, d, Decomposition) or D(f, d, CoDecomposition).
Validate that sheaves are FinSet-valued before calling decide_sheaf_tree_shape; inspect returned witness when ok==true.

Example use cases

Build a small graph and run StrDecomp(graph); print bags(d) and adhesions(d) to show the decomposition structure.
Create a Catlab diagram with FinSet nodes, lift a constraint functor via D(f, d), and show the lifted diagram for local checking.
Run decide_sheaf_tree_shape on a CoDecomposition encoding a graph-coloring instance and return ok,witness showing a valid assignment.
Demonstrate converting an ACSet schema/instance into a decomposition using acsets-bridge patterns and then decide a simple sheaf constraint.

FAQ

Do I always need CoDecomposition to decide sheaf problems?

No, but decide_sheaf_tree_shape assumes FinSet-valued sheaves and solution_space_decomp should be a CoDecomposition when you supply one. Many inspection functions differ between Decomposition and CoDecomposition.

How do I lift a functor over a decomposition?

Use the bold-D function provided by the package: D(f, d) where f is your FinSet-valued functor and d is the decomposition. Optionally pass the decomposition type as a third argument.