toolkit
Build, encode, decode, sample, inspect, optimize, and reload PhySO symbolic programs without running SR orchestration.
- License 许可
- MIT
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- toolkit
- license
- MIT
- metadata
- { "disco-role": "operating" }
- read_when
- Use when a task concerns physo.toolkit, expression prefix encodings, token libraries, free constants, program trees, display, monitoring, or Pareto/result loading.
- description
- Build, encode, decode, sample, inspect, optimize, and reload PhySO symbolic programs without running SR orchestration.
- disable-model-invocation
- true
02 资源文件 5
- 参考文档references/api-reference.md11.6 KB
- 参考文档references/troubleshooting.md7.9 KB
- 参考文档references/workflows.md10.3 KB
- 脚本scripts/check_toolkit_roundtrip.py2.3 KB
- 脚本scripts/smoke_toolkit.py2.7 KB
03 SKILL.md 正文
PhySO toolkit
Role
Use this sub-skill for the low-level symbolic-expression layer of PhySO. It
turns a token library and prefix expressions into executable Program or
VectPrograms objects, and provides safe routes for sampling, inspecting,
optimizing, displaying, and reloading those objects. The verified baseline is
PhySO 1.2.0 in a CPU-only Python environment. Import-time warnings about
missing system LaTeX are expected and do not invalidate plain-text workflows.
Boundaries
Included
physo.toolkit.get_library,get_expressions,get_prior, andsample_random_expressions.Library.encode/decode, prefix-token validation, one-hot encodings, and length/structural priors.Dataset,Tokenand its public typed subclasses,Library,Program,VectPrograms,Cursor,FreeConstantsTable, and differentiablecandidate_wrapperusage at the expression layer.- CPU-safe execution, autograd inspection, free-constant optimization, class versus realization-specific constants, tree relationships, and plain or optional display representations.
RunLogger, Pareto-front inspection,physo.read_pareto_csv,physo.read_pareto_pkl, andphyso.load_expr.
Excluded
physo.SRandphyso.ClassSRorchestration, run presets, stopping rules, and dataset/task selection. Route those questions to the SR sibling or the Class SR sibling.- Feynman/Class benchmark problem definitions, selectors, and equivalence workflows. Route them to the benchmarks sibling.
- Maintainer benchmark runners, cluster jobfile generation, long training, plotting-heavy analysis, CUDA-specific claims, and undocumented private helpers.
Verified entry points
| Need | Start here | Result |
|---|---|---|
| Define variables, constants, operations, units, and free constants | physo.toolkit.get_library(...) |
A physo.physym.library.Library |
| Encode readable prefix names | library.encode(expressions_str, one_hot=False) |
One integer-token list per expression; one_hot=True returns one-hot matrices |
| Decode integer prefixes | library.decode(expressions_idx, n_realizations=1) |
A VectPrograms batch with padded invalid placeholders |
| Make an empty program batch | physo.toolkit.get_expressions(batch_size, max_length, library, ...) |
A VectPrograms ready for append or set_programs |
| Build priors for an existing batch | physo.toolkit.get_prior(priors_config, max_length, expressions, library) |
A prior collection callable |
| Generate random valid candidates | physo.toolkit.sample_random_expressions(...) |
A sampled VectPrograms batch |
| Inspect one candidate | batch.get_prog(i) |
A Program with execution, constants, text, SymPy, and save methods |
| Inspect a batch/tree | batch.status(), batch.tokens, Cursor, family methods |
Names, arities, units, parent/child/sibling/ancestor relations |
| Fit constants | program.optimize_constants(...), batch.batch_optimize_constants(...) |
Updated constant tables and a loss history for the single-program route |
| Reload results | physo.read_pareto_pkl, physo.read_pareto_csv, physo.load_expr |
Programs or SymPy expressions, subject to the CSV/Class SR caveat |
See API reference for source-verified signatures, workflows for compact recipes, and the PhySO root skill for install/backend routing.
Operating workflow
- Fix the data contract first. For each realization, use
Xwith shape(n_dim, n_samples)andywith shape(n_samples,), both floating-point tensors or safely convertible arrays. ADatasetreceives listsmulti_Xandmulti_y, even for one realization ([X],[y]). Keep allX,y, and weights on the same device. - Build the smallest library. Set
X_names,y_name, aligned fixed and free-constant arrays, and an explicitop_nameslist. Use protected operations unless you deliberately need unprotected numerical behavior. With units, every terminal units vector must be aligned and consistent. - Encode only choosable names. Write expressions in prefix order, e.g.
['mul', 'c', 'x']. Checklibrary.choosable_names; placeholders such as the superparent, dummy, and invalid token are not encodable user tokens. - Decode and validate. Pass a batch-shaped list of Python
intindices toLibrary.decode. Inspectbatch.status(),batch.n_lengths,batch.is_complete, andbatch.get_infix_str(i)before executing. A prefix expression must be a complete tree:len(tokens) - sum(token.arity) == 1. - Sample under bounded priors. Use a small
batch_sizeandmax_lengthfor exploration. Ifpriors_configis supplied, include aHardLengthPrior; itsmax_lengthcontrols the sampler and takes precedence over the top-level value. Seed NumPy and PyTorch when a reproducible fixture matters. - Execute and inspect. Get a
Programwithget_prog, call it with a tensor, or useexecute(..., i_realization=..., n_samples_per_dataset=...)for realization-specific constants. Preferget_infix_str,get_infix_pretty, andget_infix_sympyfor non-graph output. - Optimize constants only after shapes are stable. Use differentiable
PyTorch operations and a float target. If using a
candidate_wrapper, it must be callable as(func, X) -> wrapped_outputand remain differentiable.Program.optimize_constantsuses MSE plus LBFGS by default; inspecthistory,free_consts.class_values,free_consts.spe_values,is_opti, andopti_steps. - Save and reload deliberately. Use the run visualizer/logger paths to identify the generated Pareto CSV/PKL. Prefer PKL for programs and Class SR expressions with spe constants. Use CSV loading only for non-spe Pareto fronts and pass a SymPy symbol dictionary when assumptions matter.
- Fall back when optional display tools are absent. Missing
latex,pygraphviz,dot2tex,pdflatex,pdf2image, or Pillow affects images and tree rendering, not prefix encoding or plain text. Do not turn a display dependency into a core-workflow failure.
Input/output contracts
- Library inputs:
X_nameslength must match the first dimension of data; units rows must align with their names and use at most seven dimensions.fixed_consts_units,free_consts_units, and spe-constant units align with their corresponding value/name arrays. For the toolkit convenience API,free_consts_init_valandspe_free_consts_init_valare array-like values aligned with names; low-level tokenization may use name-to-value dicts. - Prefix inputs: outer sequence is a batch; each inner sequence is a list
or NumPy array of strings for
encode, or Python integers fordecode. Variable expression lengths are accepted bydecodeand padded internally. One-hot output is for model input and is not a valid direct input todecode. - Program inputs:
Xis(n_dim, n_samples), target and weights are(n_samples,). For flattened multiple realizations, concatenate datasets in realization order and passn_samples_per_datasetwith the matching counts. - Constant outputs:
class_valueshas shape(batch_size, n_class_free_const);spe_valueshas shape(batch_size, n_spe_free_const, n_realizations). A scalar spe initializer is broadcast; a vector must have exactlyn_realizationsentries. - Monitoring outputs:
RunLogger.get_pareto_front()returns(complexities, programs, rewards, rmse).read_pareto_pklreturns a list ofProgramobjects;read_pareto_csvreturns SymPy expressions, or a(expressions, DataFrame)tuple whenreturn_df=True.
Verification and native evidence
The related native candidates are:
physo.toolkit.tests.codec_UnitTestphyso.toolkit.tests.random_sampler_UnitTestphyso.physym.tests.program_UnitTestphyso.physym.tests.vect_programs_UnitTestphyso.physym.tests.library_UnitTestphyso.physym.tests.token_UnitTestphyso.physym.tests.tokenize_UnitTestphyso.physym.tests.dataset_UnitTestphyso.physym.tests.free_const_UnitTestphyso.physym.tests.program_display_UnitTestphyso.learn.tests.monitoring_UnitTest
Run the bundled CPU-safe checks before using a generated result:
python skills/disco/physo/sub-skills/toolkit/scripts/check_toolkit_roundtrip.py
python skills/disco/physo/sub-skills/toolkit/scripts/smoke_toolkit.py
These scripts do not access the network, plot, or launch a long search. They
exercise encoding/decoding, an expected unknown-token failure, bounded random
sampling, Dataset shape handling, and a small LBFGS constant fit.
Troubleshooting
Use troubleshooting when an error is not immediately explained. In particular, check exact library names and token arity before changing code; check spe initializer and flattened-data shapes before changing an optimizer; and use text/SymPy output before installing optional renderers. If the request asks for an SR/Class SR run or a benchmark problem loader, hand it to the sibling skill instead of extending this route.
04 同仓库更多 Skills
passnet-triton-opt
Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.
passnet-solve
END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.
passnet-skill
PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.
passnet-pattern-fusion
Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.
passnet-orchestrate
Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.
passnet-feedback
Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).