docs: add agent skill for using PySR effectively - #1264
Conversation
Co-authored-by: Miles Cranmer <miles.cranmer@gmail.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4f0b5e368b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ## Constraints and complexity shaping | ||
|
|
||
| - `constraints={"pow": (9, 1)}`: max complexity of each argument (here: any base, exponent must be a lone constant/variable). `-1` means unlimited. Strongly recommended whenever `^` is included; unconstrained exponentiation searches terribly. |
There was a problem hiding this comment.
^ key for exponent constraints
When agents follow this advice with binary_operators=[..., "^"], PySR matches constraints by the actual operator name, so constraints={"pow": ...} is ignored for "^" and _process_constraints falls back to the unconstrained (-1, -1) entry while warning that ^ has no constraint. This leaves exponentiation unconstrained in the exact case the bullet is trying to prevent; use "^": (9, 1) here, or reserve "pow" for configurations where the operator is actually named pow.
Useful? React with 👍 / 👎.
| model = PySRRegressor(binary_operators=["+", "*", "^"], loss_function=objective) | ||
| ``` | ||
|
|
||
| The count-then-penalize shape (violations counted, multiplied by a large finite constant, returned *before* evaluation) is the canonical pattern: cheap structural check first, graded penalty so evolution has a direction, `Inf` reserved for failed numerical evaluation. Requiring a feature is the mirror image: `any(n -> n.degree == 0 && !n.constant && n.feature == 2, tree) || return L(big)`. For template expressions, get the tree of a component via `get_tree(ex)` inside `loss_function_expression`. More traversal tools (`tree_mapreduce`, `NodeSampler`, node construction): https://ai.damtp.cam.ac.uk/dynamicexpressions/stable/examples/base_operations/ |
There was a problem hiding this comment.
L(big) with a numeric penalty
If an agent copies this required-feature pattern literally, big is Julia's built-in conversion function rather than a numeric loss value, so return L(big) will fail when the custom objective is compiled/evaluated instead of returning the intended finite structural penalty. Use a concrete number such as L(1e6) to match the graded-penalty pattern described just before this sentence.
Useful? React with 👍 / 👎.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
2 participants
Adds a self-contained skill file at skills/pysr/SKILL.md that teaches AI coding agents to use PySR well: workflow, losses, template expressions, custom operators and objectives (including tree-walking symbolic constraints), constraints, units, parallelism, persistence, troubleshooting, and a deprecated-API translation table. Distilled from the docs plus all ~800 GitHub issues and discussions, with stale advice filtered out. The README gets a short pointer with a one-line install command in the Agent Skills format.
Validation: every code snippet and API claim was executed against live installs of both 1.5.10 and 2.0.0a2 (15-check suite, all passing). Also dogfooded with 10 fresh Sonnet agents (5 tasks, with-skill vs no-skill arms, docs access forbidden): the skill arm solved all tasks first-try with the intended mechanisms; baselines needed 2-3 attempts and reached for deprecated APIs.