diff --git a/README.md b/README.md index 6c9762d..2c24484 100755 --- a/README.md +++ b/README.md @@ -15,6 +15,32 @@ Document inputs now live under `docs/src/`: During migration, tooling still supports legacy root paths with runtime warnings. +## Gecode Skills + +Canonical Gecode skills are now maintained in: + +- `Gecode/gecode-skills` + +Install from the canonical repository: + +```bash +npx skills add Gecode/gecode-skills +``` + +List available skills: + +```bash +npx skills add Gecode/gecode-skills --list +``` + +Install a single skill: + +```bash +npx skills add Gecode/gecode-skills --skill gecode-modeling +``` + +The `skills/` directory in this repository is retained as a reference snapshot for MPG work and is not the release source for published skills. + ## Modern Tooling The project now uses a Python CLI as the primary interface: diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..1431a00 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,13 @@ +# MPG Skills Snapshot + +Canonical published Gecode skills are maintained in: + +- `Gecode/gecode-skills` + +Install from the canonical source: + +```bash +npx skills add Gecode/gecode-skills +``` + +This `skills/` directory is kept as a reference snapshot for MPG and local iteration, and is not the release source for skills published via `npx skills add`. diff --git a/skills/case-study-skill-audit.md b/skills/case-study-skill-audit.md new file mode 100644 index 0000000..90433c6 --- /dev/null +++ b/skills/case-study-skill-audit.md @@ -0,0 +1,43 @@ +# MPG Case-Study Skill Audit + +Scope: `/Users/zayenz/gecode/MPG/docs/src/chapters/case-studies/*.tex.in` + +## Per-Case Findings + +| Case study | Important issues / patterns | Category | Skill mapping | Coverage before | Action | +|---|---|---|---|---|---| +| `c-photo.tex.in` | Objective via `cost()`, propagation-level alignment (`distinct` BND), reversal symmetry break | Optimization + symmetry | `gecode-modeling` | Partial | Added symmetry + propagation-level guidance | +| `c-golomb.tex.in` | Tight bounds to avoid overflow risk, implied constraints, symmetry break, cost-driven branching | Modeling strength | `gecode-modeling` | Partial | Added implied-constraint and symmetry bullets | +| `c-golf.tex.in` | Set-model symmetry reduction + extra symmetry breaking (`precede`, ordering) | Symmetry design | `gecode-modeling` | Weak | Added structural symmetry guidance | +| `c-magic-sequence.tex.in` | Individual `count` vs global counting, implied linear constraints, value-order heuristic | Global-vs-decomposition | `gecode-modeling` | Partial | Added global-constraint replacement rule | +| `c-nonogram.tex.in` | Regex/extensional modeling, AFC branching, propagation-only vs custom branching need | Search/branching fit | `gecode-modeling`, `gecode-brancher-implementation` | Partial | Added brancher heuristic emphasis | +| `c-knights.tex.in` | `circuit(..., IPL_DOM)`, symmetry via fixed move, custom Warnsdorff brancher | Problem-specific brancher | `gecode-brancher-implementation`, `gecode-modeling` | Partial | Added heuristic-brancher pattern | +| `c-kakuro.tex.in` | Naive `distinct+linear` decomposition weak, `IPL_DOM` linear cost tradeoff, extensional tuple-set surrogate, tuple-set cache opportunity | Propagation strength + modeling perf | `gecode-modeling`, `gecode-propagator-implementation` | Gap | Added decomposition-warning + cache guidance | +| `c-warehouses.tex.in` | `count` + `element` + `linear` composition, mixed int/bool cost expression, two-stage branching | Optimization modeling | `gecode-modeling` | Partial | Added cost-driven branching guidance | +| `c-bin-packing.tex.in` | Naive vs `binpacking` global, CDBF custom brancher, symmetry in branching, heap choice payload + `AP_DISPOSE`, region scratch, shared arrays | High-impact full-stack pattern | `gecode-modeling`, `gecode-brancher-implementation`, `gecode-memory-handling`, `gecode-general-knowledge` | Gap/partial | Added all four skills | +| `c-crossword.tex.in` | Memory reductions (variable elimination/shared arrays), branch print hooks, restart+no-goods+AFC robustness | Search robustness + memory | `gecode-modeling`, `gecode-memory-handling`, `gecode-general-knowledge` | Partial | Added memory + iterative tuning guidance | + +## Priority Synthesis + +### P0 (applied) +- Symmetry as mandatory design axis in modeling and branching. +- Global-constraint substitution for weak decompositions. +- Propagation-level cost awareness (`IPL_DOM` selectively). +- Problem-specific branchers for structure-heavy problems. + +### P1 (applied) +- Memory patterns from case studies: shared arrays, region scratch, `AP_DISPOSE` lifecycle discipline. +- Iterative optimization loop: baseline -> propagation -> branching -> restart/no-good tuning. + +### P2 (applied lightly) +- Propagator skill now explicitly calls out decomposition weakness and cacheable support data. + +## Skill Updates Applied + +- Updated `/Users/zayenz/gecode/MPG/skills/gecode-general-knowledge/SKILL.md` +- Updated `/Users/zayenz/gecode/MPG/skills/gecode-modeling/SKILL.md` +- Updated `/Users/zayenz/gecode/MPG/skills/gecode-propagator-implementation/SKILL.md` +- Updated `/Users/zayenz/gecode/MPG/skills/gecode-brancher-implementation/SKILL.md` +- Updated `/Users/zayenz/gecode/MPG/skills/gecode-memory-handling/SKILL.md` + +No new skill created: existing five skills cover all extracted case-study learnings after update. diff --git a/skills/gecode-brancher-implementation/SKILL.md b/skills/gecode-brancher-implementation/SKILL.md new file mode 100644 index 0000000..973c9e1 --- /dev/null +++ b/skills/gecode-brancher-implementation/SKILL.md @@ -0,0 +1,38 @@ +--- +name: gecode-brancher-implementation +description: "Implement custom Gecode branchers and choice mechanics: status/choice/commit, archiving, recomputation compatibility, no-good literal support, and brancher view reuse. Use when predefined `branch(...)` is insufficient." +--- + +# Gecode Brancher Implementation + +## Core +- Brancher is actor implementing branching behavior. +- Implement `status`, `choice(Space&)`, `choice(const Space&,Archive&)`, `commit`, `print`, `copy`, `dispose`. +- Choice stores only space-independent commit data. +- `commit` must work with recomputed/cloned spaces using only choice payload. +- Choices must be archive-compatible and deterministic. +- Branchers execute in queue order of posting. +- Optional `ngl()` adds no-good support. +- Brancher `status()==false` does not imply immediate disposal; commits for earlier choices must remain valid. + +## Key Patterns +- Track first candidate index (`start`) to avoid rescanning. +- Keep choice payload minimal (`pos`, `val`, alt count), archive/unarchive deterministically. +- Use binary alternatives (`eq` vs `nq`) unless assignment brancher (single alt). +- Implement NGL class with `status`, `prune`, `subscribe`, `cancel`, `reschedule`. +- For complementary last alternatives, `ngl()` can return `NULL` when semantically valid. +- Reuse branchers through views (notably minus view for max-style variants). +- Encode problem heuristic explicitly (for example Warnsdorff, best-fit slack). +- Mix assignment-style one-alt choices with pruning alternatives when justified. +- Design second alternatives to embed symmetry breaking when safe. +- Pair brancher with branch print callbacks for explainability/debugging. + +## Pitfalls +- Storing views/pointers to space state inside choice objects. +- Disposing brancher too early when `status()` becomes false. +- Depending on mutable brancher state not encoded in choice for `commit()`. +- Using choices after invalidation by a later `choice()` call on the same space. +- Not skipping assigned views, causing repeated same choice/infinite tree. +- Violating recomputation invariants and commit order assumptions. +- Using generic variable-value branching when structure-aware heuristic is required. +- Forgetting that brancher disposal is not automatic when external resources exist. diff --git a/skills/gecode-brancher-implementation/agents/openai.yaml b/skills/gecode-brancher-implementation/agents/openai.yaml new file mode 100644 index 0000000..6c115f3 --- /dev/null +++ b/skills/gecode-brancher-implementation/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Gecode Brancher Implementation" + short_description: "Implement custom Gecode branchers and NGLs" + default_prompt: "Provide concise implementation guidance for Gecode branchers, choices, commits, and NGL support." diff --git a/skills/gecode-general-knowledge/SKILL.md b/skills/gecode-general-knowledge/SKILL.md new file mode 100644 index 0000000..c08c598 --- /dev/null +++ b/skills/gecode-general-knowledge/SKILL.md @@ -0,0 +1,39 @@ +--- +name: gecode-general-knowledge +description: "Core Gecode architecture and runtime model: spaces, propagators, branchers, status/choice/clone/commit lifecycle, cloning/recomputation semantics, groups/tracing. Use when explaining solver behavior, search flow, or high-level debugging/design decisions." +--- + +# Gecode General Knowledge + +## Core +- Space is home for variables, propagators, branchers, optimization order. +- Propagation is explicit: call `status()`. +- Search primitives: `status()`, `choice()`, `clone()`, `commit()`, `constrain()`. +- Space status: `SS_FAILED`, `SS_SOLVED`, `SS_BRANCH`. +- Choice is space-independent descriptor; alternatives indexed `0..n-1`. +- Choice compatibility is clone-based: a choice is compatible with its source space and clones. +- `choice()` invalidates previous choices for later `commit()` on that space. +- Clone only stable, non-failed spaces. +- Branchers run in posting order. +- Recomputation can be nondeterministic with weakly monotonic propagation, while remaining sound/complete. + +## Key Patterns +- Model as `class M : public Space`. +- Implement copy constructor + virtual `copy()`. +- In space cloning, clone variable arrays via `x.update(home, s.x)`; do not use a variable-array copy constructor. +- After `status()==SS_BRANCH`, compute `choice()` immediately. +- Seed search engine with model, then delete seed model. +- Treat solution as space closure over member variables. +- Use groups/tracing for observability, selective control. +- Iterate model quality in loops: baseline -> improve propagation -> improve branching -> tune search. +- Measure with nodes/time/restarts, not runtime only. +- Treat symmetry handling as first-class design work, not post-processing. + +## Pitfalls +- Assuming posting runs full propagation. +- Calling `Space` copy constructor directly instead of `clone()`. +- Using stale choices after invalidating via later `choice()` usage. +- Forgetting ownership/deletion of choices and returned solution spaces. +- Cloning unstable/failed spaces. +- Assuming parallel search preserves sequential solution order or runtime profile. +- Assuming one modeling pass is enough; most case studies need staged refinement. diff --git a/skills/gecode-general-knowledge/agents/openai.yaml b/skills/gecode-general-knowledge/agents/openai.yaml new file mode 100644 index 0000000..942c9bc --- /dev/null +++ b/skills/gecode-general-knowledge/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Gecode General Knowledge" + short_description: "Core Gecode architecture and workflow guide" + default_prompt: "Explain core Gecode concepts, spaces, propagation, and search operations concisely." diff --git a/skills/gecode-memory-handling/SKILL.md b/skills/gecode-memory-handling/SKILL.md new file mode 100644 index 0000000..a183f31 --- /dev/null +++ b/skills/gecode-memory-handling/SKILL.md @@ -0,0 +1,37 @@ +--- +name: gecode-memory-handling +description: "Manage Gecode memory areas and actor state: space/region/heap/freelists, lazy vs eager state allocation, shared/local handles, and disposal obligations (`AP_DISPOSE`). Use when implementing memory-sensitive propagators/branchers." +--- + +# Gecode Memory Handling + +## Core +- Memory areas: space, region, heap, space freelists. +- `alloc/realloc/free` follow C++ object lifecycle semantics. +- Space memory auto-reclaimed on space deletion; good for stable-size actor data. +- Region is temporary arena; implicit free on region destruction. +- Heap is for frequently resized/dynamic structures. +- Search memory profile favors pristine clones; allocation timing matters. +- Shared handles: cross-space/thread shared heap object with refcount. +- Local handles: per-space shared object, copied on cloning. + +## Key Patterns +- Allocate fixed actor members in home space. +- Allocate resize-heavy buffers on heap; free in `dispose()`. +- Build heavy internal state lazily on first propagation when possible. +- Choose eager vs lazy vs hybrid allocation based on clone-footprint and hit rate. +- Use regions for short-lived temporary iterators/buffers. +- Explicitly `Region::free()` at clear control-flow boundaries to maximize reuse. +- Use `SharedHandle` for immutable/global lookup data. +- Use `LocalHandle` for shared per-space mutable state. +- Use `IntSharedArray`/shared arrays for read-only large data reused across clones. +- For brancher choices using heap buffers, pair allocation/free and register `AP_DISPOSE`. +- Use `Region` for per-choice scratch arrays to avoid heap churn. + +## Pitfalls +- Frequent resize in space memory causing fragmentation. +- Forgetting `home.notice(..., AP_DISPOSE)` for external/heap resources. +- Forgetting matching `home.ignore(..., AP_DISPOSE)` in dispose path. +- Assuming same alignment guarantees across space vs heap/region. +- Leaking ownership assumptions across cloning boundaries. +- Allocating per-choice temporary arrays on heap in hot paths. diff --git a/skills/gecode-memory-handling/agents/openai.yaml b/skills/gecode-memory-handling/agents/openai.yaml new file mode 100644 index 0000000..6366222 --- /dev/null +++ b/skills/gecode-memory-handling/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Gecode Memory Handling" + short_description: "Manage Gecode memory and shared/local state" + default_prompt: "Summarize concise best practices for Gecode memory areas, lifecycle, and handle-based sharing." diff --git a/skills/gecode-modeling/SKILL.md b/skills/gecode-modeling/SKILL.md new file mode 100644 index 0000000..134f6d3 --- /dev/null +++ b/skills/gecode-modeling/SKILL.md @@ -0,0 +1,45 @@ +--- +name: gecode-modeling +description: "Model CP problems in Gecode with Int/Bool/Set/Float variables, constraints, MiniModel expressions, branchings, and search configuration. Use when building or refining Gecode models and solver setup." +--- + +# Gecode Modeling + +## Core +- Define model as `Space` subclass. +- Create typed variable arrays with tight domains early. +- Post constraints via post functions (`rel`, `linear`, `distinct`, set/float variants). +- Post branching via `branch(...)`; variable strategy + value strategy define tree shape. +- Use search engines (`DFS`, `BAB`, restart/portfolio variants) per objective. +- MiniModel adds expression syntax via `expr(...)`, `rel(...)`, matrix/channel helpers. +- Reified modeling supports full and half reification; decomposition semantics matter. + +## Key Patterns +- Prefer global constraints over manual decompositions when available. +- Keep branchings explicit and problem-specific for scale. +- Use multiple branchers intentionally; creation order matters. +- Tune search options: recomputation distance, restarts, no-goods, stop objects. +- Use tracing/Gist/CPProfiler for model diagnostics. +- Add implied constraints aggressively when semantics unchanged but propagation improves. +- Break symmetry structurally: order constraints, fixed anchors, `precede`, monotone bins. +- Use LDSB only with supported branching/value configurations; validate symmetry assumptions. +- Match propagation level to complexity (`IPL_DOM` only where payoff > cost). +- Replace weak decompositions with stronger globals (`count` GCC, `binpacking`, `circuit`, `extensional`). +- Cache reusable heavy artifacts (tuple sets, shared arrays) keyed by shape/parameters. +- For arrays requiring non-shared vars, call `unshare(...)` once and reuse the result. +- Use branch filters/print functions for targeted branching and observability. +- When executing code between branchers, remember propagation is still explicit on recomputation paths. +- For optimization models, branch on cost-driving vars first, tie with objective structure. + +## Pitfalls +- Weak domains at model start causing huge trees. +- Forgetting to update all variable members in cloning constructor. +- Assuming MiniModel nonlinear expressions stay monolithic; many decompose. +- Assuming reified non-functional decompositions imply `b=false`; they can fail instead. +- Treating Boolean vars as subclass of integer vars. +- Ignoring exceptions from invalid arguments/overflow. +- Using domain propagation for `linear` indiscriminately (can be exponential). +- Recomputing identical tuple sets/shared maps per post. +- Repeated implicit-style unsharing patterns that create unnecessary vars/propagators. +- Combining LDSB with unrelated static symmetry breaking without safety analysis. +- Leaving major value/variable symmetries unbroken. diff --git a/skills/gecode-modeling/agents/openai.yaml b/skills/gecode-modeling/agents/openai.yaml new file mode 100644 index 0000000..dd3bb29 --- /dev/null +++ b/skills/gecode-modeling/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Gecode Modeling" + short_description: "Model Gecode CP problems and search setup" + default_prompt: "Guide concise Gecode modeling choices, constraints, branchings, and search configuration." diff --git a/skills/gecode-propagator-implementation/SKILL.md b/skills/gecode-propagator-implementation/SKILL.md new file mode 100644 index 0000000..b6fe4ed --- /dev/null +++ b/skills/gecode-propagator-implementation/SKILL.md @@ -0,0 +1,40 @@ +--- +name: gecode-propagator-implementation +description: "Implement and optimize custom Gecode propagators: posting, propagate/reschedule lifecycle, propagation conditions, domain iterators, advisors, reification, and rewriting. Use when adding new constraints or improving propagation performance/safety." +--- + +# Gecode Propagator Implementation + +## Core +- Propagator computes on views, not model variables. +- Implement post function + actor lifecycle (`copy`, `dispose`, `cost`, `reschedule`, `propagate`). +- Use `Home` for posting context; use fail/check macros. +- Return honest `ExecStatus`: `ES_FAILED`, `ES_SUBSUMED`, `ES_FIX`, `ES_NOFIX`. +- Respect obligations: correctness, checking, contracting, monotonicity (or waived), subscription completeness, update completeness. +- Respect implementation obligations: subsumption complete, cloning conservative, subscription correct. +- Use patterns (`Unary/Binary/Ternary/Nary`, mixed variants) to reduce boilerplate. + +## Key Patterns +- Do cheap pruning in `post()`; skip posting when trivially subsumed/failed. +- Select minimal propagation conditions (`*_VAL`, `*_BND`, `*_DOM`). +- Prefer iterator-based domain ops (`inter_r`, `narrow_r`, `minus_r`) for domain propagation. +- Use fixpoint reasoning deliberately: return `ES_FIX` only when justified. +- Use `ModEventDelta` and staging to combine cheap and expensive propagation phases. +- Use advisors for incremental change localization. +- For advisors, maintain council lifecycle and ensure rescheduling/subscription completeness. +- Rewrite propagators (`GECODE_REWRITE`) when state simplifies. +- Use reified/rewriting patterns to remove reification overhead once control literals decide. +- Template propagators on view types for reuse. +- If decomposition is propagation-weak, prefer dedicated propagator or extensional surrogate. +- Treat expensive support data as cacheable object, not per-post recomputation. + +## Pitfalls +- Modifying a view while iterating its domain iterator. +- Returning `ES_FIX` when not actually at fixpoint. +- Returning `ES_NOFIX` when propagation is idempotent and could reach fixpoint inside the same `propagate()` call (causes avoidable re-scheduling). +- Missing view updates/subscription cancellation during cloning/disposal. +- Using external resources without `AP_DISPOSE` notice/ignore discipline. +- Continuing execution after subsuming/disposing actor. +- Failing to check modification-event failure after view updates. +- Breaking subscription completeness when using advisors/dynamic subscriptions. +- Expecting two weak propagators (`distinct` + `linear`) to match joint reasoning of one stronger constraint. diff --git a/skills/gecode-propagator-implementation/agents/openai.yaml b/skills/gecode-propagator-implementation/agents/openai.yaml new file mode 100644 index 0000000..e975e10 --- /dev/null +++ b/skills/gecode-propagator-implementation/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Gecode Propagator Implementation" + short_description: "Implement custom Gecode propagators safely" + default_prompt: "Provide concise implementation guidance for Gecode propagators, obligations, and optimization." diff --git a/skills/gecode-search-engine-implementation/SKILL.md b/skills/gecode-search-engine-implementation/SKILL.md new file mode 100644 index 0000000..27fc33a --- /dev/null +++ b/skills/gecode-search-engine-implementation/SKILL.md @@ -0,0 +1,38 @@ +--- +name: gecode-search-engine-implementation +description: "Implement custom Gecode search engines: status/choice/clone/commit orchestration, recomputation strategies (full/hybrid/adaptive), last-alternative optimization, branch-and-bound integration, and invariants for choice compatibility and completeness." +--- + +# Gecode Search Engine Implementation + +## Core +- Implement engines against the `Space` interface (`status`, `choice`, `clone`, `commit`). +- Maintain explicit ownership for all `Space*` and `Choice*` objects. +- Respect compatibility invariants: choices are valid only for clone-related spaces. +- Treat `choice()` as invalidating earlier choices on that space. +- Handle all `SpaceStatus` cases: `SS_FAILED`, `SS_SOLVED`, `SS_BRANCH`. + +## Key Patterns +- Keep a clear split between exploration mode and recomputation mode. +- Use edge/path state to store choices, alternatives, and optional clones. +- For recomputation, replay commits from nearest stored clone (or root clone). +- Apply LAO (last-alternative optimization) to avoid unnecessary stored choices/commits. +- Use hybrid recomputation with commit distance to cap recomputation cost. +- Use adaptive recomputation to add clones where repeated failures indicate benefit. +- Integrate branch-and-bound by constraining future spaces against best solution. +- Keep restart/meta-engine hooks explicit (`master`, `slave`) when required. +- Wire statistics and stop-object checks consistently. + +## Invariants +- Recomputed spaces must follow the same decision path as stored edge choices. +- Commit order must match original choice generation order. +- If recomputation fails due to nondeterminism/weak monotonicity effects, recover path state safely and continue search. +- Cloning/copying must never mutate model state outside allowed operations. + +## Pitfalls +- Reusing stale choices after another `choice()` call. +- Mixing incompatible choices/spaces and triggering `SpaceNoBrancher`. +- Forgetting to delete choices and returned solution spaces. +- Assuming deterministic node order under parallel execution. +- Overusing no-goods depth without accounting for memory and LAO tradeoffs. +- Reporting completeness when stop/cutoff/meta policy makes the run incomplete. diff --git a/skills/gecode-search-engine-implementation/agents/openai.yaml b/skills/gecode-search-engine-implementation/agents/openai.yaml new file mode 100644 index 0000000..0b1085b --- /dev/null +++ b/skills/gecode-search-engine-implementation/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Gecode Search Engine Implementation" + short_description: "Implement custom Gecode search engines safely" + default_prompt: "Guide implementation of a custom Gecode search engine, including recomputation, invariants, ownership, and branch-and-bound integration." diff --git a/skills/gecode-search-engines/SKILL.md b/skills/gecode-search-engines/SKILL.md new file mode 100644 index 0000000..8277987 --- /dev/null +++ b/skills/gecode-search-engines/SKILL.md @@ -0,0 +1,50 @@ +--- +name: gecode-search-engines +description: "Use existing Gecode search engines and meta-engines effectively: DFS/BAB/LDS, restart and portfolio setup, no-goods, parallel behavior, and completeness tradeoffs. Use when selecting/tuning search, not implementing new engines." +--- + +# Gecode Search Engines + +## Core +- This skill is for using built-in engines, not implementing custom engines. +- Base engines: `DFS`, `BAB`, `LDS`. +- Meta engines: `RBS` (restart-based) and `PBS` (portfolio-based). +- Key options live in `Search::Options` (`threads`, `c_d`, `a_d`, `clone`, `stop`, `cutoff`, `nogoods_limit`, `assets`, `slice`, `tracer`). +- For optimization, use `BAB`-style search with a valid model-side objective/constrain setup. + +## Engine Selection +- Use `DFS` for baseline complete search/enumeration. +- Use `BAB` for best-solution search. +- Use `LDS` when the branching heuristic is strong and you want discrepancy-ordered exploration. +- Use `RBS` to improve robustness via cutoffs, restart policies, and optional no-goods. +- Use `PBS` to improve robustness via asset diversification (heuristics/models/engines/options). + +## Restart, Portfolio, and Incomplete Search Interactions +- `RBS` requires a cutoff generator in options. +- In restart search, `master()` decides restart behavior and can post no-goods; `slave()` configures each restart run. +- In restart search, `slave()` return value matters: + `true` means complete slave search; `false` means intentionally incomplete search (for example LNS neighborhoods). +- In portfolio search, `slave()` return value has no meaning. +- `PBS` uses one engine type per asset; mixed portfolios use `SEBs(...)` to combine `dfs/lds/bab/rbs/pbs` with per-asset options. +- Do not mix best-solution and non-best assets in one SEB portfolio (`Search::MixedBest`). +- For restart-based best-solution assets in portfolios, use `RBS`. + +## No-Good Nuances +- Restart no-goods are only available from `DFS`/`BAB`, not `LDS`. +- Enable with `nogoods_limit > 0`; depth is a memory/benefit tradeoff. +- Larger no-good depth limits reduce LAO effectiveness near root and can significantly increase memory. +- Not all branchers support no-goods; float branchers and execution branchers do not. +- Parallel search usually yields fewer extractable no-goods. + +## Parallel and Portfolio Semantics +- Parallel search is intentionally nondeterministic (solution order, node counts, runtime). +- `assets` and `threads` are allocated conservatively in portfolios. +- Sequential portfolios use failure slices (`slice`) per asset (round-robin). +- With `threads > assets`, extra threads can be used inside asset engines. + +## Pitfalls +- Expecting deterministic behavior from restart/portfolio/parallel runs. +- Treating restart/portfolio as complete when stop conditions, cutoffs, or `slave()==false` make runs incomplete. +- Forgetting to diversify assets and then expecting portfolio gains. +- Assuming no-goods are always available/effective regardless of brancher mix and parallelism. +- Forgetting that `master()`/`slave()` policy choices directly change search completeness and restart behavior. diff --git a/skills/gecode-search-engines/agents/openai.yaml b/skills/gecode-search-engines/agents/openai.yaml new file mode 100644 index 0000000..40c8de5 --- /dev/null +++ b/skills/gecode-search-engines/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Gecode Search Engines" + short_description: "Use and tune existing Gecode search engines" + default_prompt: "Recommend and configure Gecode DFS/BAB/LDS/RBS/PBS usage, including restart/portfolio/no-good and completeness tradeoffs." diff --git a/skills/install-skills.sh b/skills/install-skills.sh new file mode 100755 index 0000000..50683c2 --- /dev/null +++ b/skills/install-skills.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Local snapshot installer for MPG development. +# Canonical published skills are in Gecode/gecode-skills. + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +DEST_DEFAULT="${HOME}/.codex/skills" +DEST="${1:-${CODEX_HOME:-$DEST_DEFAULT}/skills}" + +if [[ "$DEST" == "$HOME/.codex/skills/skills" ]]; then + DEST="$HOME/.codex/skills" +fi + +mkdir -p "$DEST" + +echo "Note: canonical published skills are in Gecode/gecode-skills (npx skills add Gecode/gecode-skills)." +echo "Installing MPG snapshot copies into: $DEST" + +for skill in \ + gecode-general-knowledge \ + gecode-modeling \ + gecode-propagator-implementation \ + gecode-brancher-implementation \ + gecode-memory-handling \ + gecode-search-engines \ + gecode-search-engine-implementation; do + rm -rf "$DEST/$skill" + cp -R "$SCRIPT_DIR/$skill" "$DEST/$skill" + echo "installed: $DEST/$skill" +done