generation
Route safe MatterGen crystal generation from pretrained or local checkpoints, including unconditional, property-conditional, multi-property, CSP composition-targeted sampling, sampling overrides, trajectories, and the CrystalGenerator API.
- License 许可
- MIT
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- generation
- license
- MIT
- metadata
- { "disco-role": "operating" }
- description
- Route safe MatterGen crystal generation from pretrained or local checkpoints, including unconditional, property-conditional, multi-property, CSP composition-targeted sampling, sampling overrides, trajectories, and the CrystalGenerator API.
- disable-model-invocation
- true
02 资源文件 5
- 参考文档references/api-reference.md5.5 KB
- 参考文档references/model-overview.md4.7 KB
- 参考文档references/troubleshooting.md5.1 KB
- 参考文档references/workflows.md5.9 KB
- 脚本scripts/generate_materials.py15.0 KB
03 SKILL.md 正文
MatterGen generation
Use this sub-skill when the task is to generate inorganic crystal candidates with
MatterGen 1.0.3. It owns checkpoint selection, conditioning, CSP compositions,
sampling configuration, output artifacts, and the public CrystalGenerator API.
It does not own training, fine-tuning, relaxation/evaluation, dataset
creation, or paper-result interpretation; route those tasks to the appropriate
MatterGen skill instead.
Route before running
- Decide whether the checkpoint is a named pretrained model or a local
checkpoint directory.
pretrained_nameandmodel_pathare mutually exclusive, and at least one is required. - Decide whether the request is unconditional, property-conditioned, or CSP.
CSP means fixed element counts and requires a CSP-trained checkpoint plus the
cspsampling config; a normal base checkpoint cannot be turned into CSP by adding a composition argument. - Check that every requested property is a condition the selected checkpoint was trained to accept. For the catalog and known condition sets, read model-overview.md.
- Bound
batch_size * num_batches, GPU memory, trajectory storage, and output location before loading a model. Use the safe validator first: scripts/generate_materials.py. - Read workflows.md for the matching invocation and troubleshooting.md before retrying failures.
Supported routes
- Unconditional: use
mattergen_baseormp_20_basewith no property map and no target composition.diffusion_guidance_factor=0.0is unconditional behavior. - Single property: use a compatible fine-tuned model and pass a mapping such
as
{'dft_mag_density': 0.15}. The CLI is Fire-based; quote the whole map and do not put whitespace around its key/value separator. - Multiple properties: pass one mapping, for example
{'energy_above_hull': 0.05, 'chemical_system': 'Li-O'}, to a checkpoint trained jointly for those conditions. A property name being globally known does not prove that every checkpoint supports it. - CSP: pass a list of element-count mappings, such as
[{'Na': 1, 'Cl': 1}], and--sampling-config-name=csp. The CSP config omits atomic-number predictor/corrector parts because atom types are fixed by the requested composition. Use a CSP-trained local model; the public pretrained catalog is primarily the non-CSP catalog. - Python API: construct
MatterGenCheckpointInfo, thenCrystalGenerator, and callgenerate. Use the exact public signatures in api-reference.md; do not reproduce private model-loading internals in a caller script.
Safe execution procedure
- Run the bundled helper with
--help, then without--run, to parse and validate the request. It never downloads a checkpoint or starts sampling by default. Fix errors before using--run. - For a Hub model, verify network/cache permission and choose a small smoke
batch first.
MatterGenCheckpointInfo.from_hf_hub(...)downloads missing files only when explicitly running. For a local model, verify its directory containsconfig.yamland hydrated checkpoint files; a Git-LFS pointer is not a usable checkpoint. - Set
--record-trajectories=False(native CLI spelling) when trajectory ZIPs are not needed. Keep the first run small; increase batch size only after a successful memory smoke test. MatterGen selects CUDA when available, then MPS, then CPU; generation is substantially slower and may be impractical on CPU. - Run into a new or deliberately chosen output directory. Never assume a partially written output is a complete sample set.
- Inspect the returned/generated structure count and the expected files:
generated_crystals_cif.zip,generated_crystals.extxyz, and, when enabled,generated_trajectories.zip. Preserve the resolved checkpoint/config and sampling overrides with the experiment record outside this skill tree.
Conditioning and guidance rules
properties_to_condition_on is a dict whose keys must be model-supported
property source IDs. diffusion_guidance_factor is the classifier-free guidance
weight: 0 selects the unconditional score, 1 selects the conditional score,
and larger nonnegative values increasingly favor the requested condition while
usually reducing diversity/realism. Guidance cannot add a missing property
head, repair malformed values, or make an incompatible checkpoint conditional.
sampling_config_overrides are Hydra override strings. The installed default
sampling configuration uses 1,000 diffusion steps and atom-number denoising;
the installed CSP configuration uses composition conditioning and omits
atomic-number denoising. Use overrides only for known config keys and record
them exactly. Avoid changing sampler fields until a baseline completes.
Failure recovery
- Missing assets: stop and acquire/hydrate the selected checkpoint (Hub or LFS); do not confuse CUDA readiness with asset readiness.
- Import/backend errors: run the helper's validation without
--run, then use the environment's publicpython -cimport/help probes. Check optional ASE, PyTorch Geometric CUDA wheels,pymatgen, Hydra, and MatterSim dependencies; do not silently switch to a different package version. - Config/condition errors: reduce to an unconditional one-batch run, then add one condition, then multiple conditions. For CSP, switch both the checkpoint and config rather than only changing the CLI flag.
- Out-of-memory or stalled jobs: lower
batch_size, lowernum_batches, turn off trajectories, and retry in a fresh output directory. Do not infer model quality from an interrupted run. - Output errors: ensure the output directory is writable and has space; verify ZIP members and frame count before downstream evaluation.
Bundled operating material
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).