materials-design

name

materials-design

description

Design and prioritize candidate materials from tabular experimental or computational data. Use when identifying controllable material descriptors and one or more target properties, fitting and validating surrogate models, defining a feasible search space, optimizing single- or multi-objective performance, quantifying uncertainty, or preparing a reproducible materials-discovery recommendation report.

Materials Design

Turn a tabular materials dataset into a conservative, reproducible candidate-ranking workflow. Treat recommendations as hypotheses for validation, not as confirmed materials or synthesis advice.

Required output contract

Create a new, non-overwriting output directory at research/materials-design/<run-name>/ in the user's project. Before doing substantive analysis, create report.html there from assets/report-template.html. Fill every relevant section as the work proceeds and save generated figures beside it in figures/ using relative links.

report.html is required for every invocation. Do not finish with a prose-only chat response, a plan, or a list of commands. If the data, targets, or candidate space are incomplete, create a readiness report instead: state the available inputs, missing requirements, risks of proceeding, and the exact next data needed. Do not fabricate results to fill the report.

Before the final response, verify that report.html exists and is non-empty. Return its project-relative path along with the paths of the raw-data reference, configuration, candidate space, predictions, and shortlist that were created. If filesystem writing is unavailable, say so explicitly before presenting any analysis and provide the complete HTML as a fenced code block only as a fallback.

Intake and scope

Establish the decision before modeling:

• Identify each column as an identifier, controllable design variable, measured descriptor, target, grouping variable, or unusable leakage field. Confirm which variables can actually be set during design.
• Define target direction and acceptable bounds. For multiple targets, identify trade-offs, hard constraints, and whether a Pareto set is more useful than one scalar score.
• Record data provenance, units, measurement conditions, missing-value semantics, duplicate handling, and any known feasibility or safety constraints.
• Require a candidate/design space: an enumerated table, allowed category sets, numeric bounds and increments, or generation rules. If it is unavailable, ask for it. Only generate a provisional in-domain space from observed controllable-variable ranges after clearly labelling that assumption.

Do not optimize an identifier, a post-measurement variable, or a column that leaks the target. Do not extrapolate beyond the supplied feasible range without explicit user approval.

Prepare the data

1. Preserve the raw input and create a data dictionary with column roles, units, transformations, and exclusions.
2. Remove exact duplicates only after checking whether they are replicates. Aggregate replicates only with a documented rule; retain their spread when available.
3. Build a deterministic preprocessing pipeline. Keep identifiers out of the feature matrix; preserve categorical variables as categories; convert numeric strings only after validating units and decimal conventions. Encode composition variables consistently and enforce composition closure where applicable.
4. Handle missingness explicitly. Report it by column and target. Drop a row only when its required target is unavailable or the rule is justified; impute features with a training-fold statistic or a model-compatible imputer, and add missingness indicators when missingness may be informative. Never impute target labels for supervised training or validation.
5. Inspect implausible values, unit mismatches, and outliers before removal. Correct only traceable data-entry errors; otherwise retain the observation, flag it, and compare sensitivity with and without the justified exclusion. Do not use target-aware outlier removal.
6. Split data before fitting every learned preprocessing step. Impute, transform, scale, encode, and select features within each cross-validation training fold, then apply the fitted pipeline to its validation fold and the candidate space. Persist the fitted transformation settings with the selected model.
7. Standardize continuous descriptors with training-fold z-scores for scale-sensitive models such as SVM, GPR, regularized linear models, and distance-based methods. Leave tree ensembles unscaled unless scaling is part of a shared pipeline. For strongly right-skewed, strictly positive features, consider a documented log or power transform before standardization; define how zeros and negatives are handled. Avoid scaling binary indicators unless the selected model requires it.
8. Transform targets only when it improves model assumptions or target scale comparability. Fit target transforms in each training fold, invert predictions before reporting MAE/RMSE and candidate properties, and clearly label any metrics computed in transformed space.
9. Use group- or time-aware splits when samples from the same composition family, batch, publication, or campaign are correlated. Otherwise use shuffled K-fold cross-validation: typically 5 folds for fewer than 100 rows and 5–10 folds for larger datasets, subject to class/group feasibility.
10. State when data volume, target noise, or coverage makes reliable optimization impossible. In that case, return an exploration or data-collection plan rather than overconfident rankings.

Fit and evaluate surrogate models

Fit a compact, diverse model set appropriate to the data: regularized linear model, random forest, extra trees, gradient boosting, support-vector regression, Gaussian process regression (GPR), and XGBoost only when the dependency is available and the data size supports it. For categorical-only or mixed descriptors, choose encoders and models compatible with the data.

• Use identical folds and the same preprocessing protocol for all models.
• Compare out-of-fold predictions against observed targets. Report mean and fold-wise R², MAE, RMSE, and Spearman correlation; avoid R² alone.
• Inspect residuals by target magnitude, composition family/group, and key design variables. Flag systematic failure, tiny effective sample size, unstable fold scores, or poor coverage.
• Select a model for predictive reliability, stability, and calibration—not solely the highest average score. Retain the comparison table and random seeds.
• For each target, use the chosen surrogate only if held-out performance supports its use; otherwise communicate that rankings are exploratory.

Estimate uncertainty

Use predictive uncertainty in acquisition and reporting.

• Use posterior mean and standard deviation from a suitably fitted GPR when available and calibrated.
• For models without native uncertainty, estimate epistemic uncertainty with a documented ensemble or bootstrap refit procedure. Generate each resample, preprocessing fit, and prediction independently within the resampling workflow.
• Check calibration on out-of-fold residuals or held-out data. If it is poorly calibrated, present uncertainty as a relative confidence signal rather than a probability.
• Do not claim experimental error bars from model variance alone.

Define and search the design space

Use the user-provided candidate table whenever possible. Apply hard constraints before prediction: chemical validity, composition closure, processing limits, cost/availability rules, stability requirements, and user-specified exclusions.

For a generated discrete space, derive ranges only from controllable variables, choose practical increments, deduplicate candidates, and report its size. Use a space-filling or orthogonal design only to construct or down-select a provisional space; do not imply that it validates the candidates. Avoid arbitrary expansion to a fixed candidate count—search density must be justified by resolution, constraints, and compute budget.

Rank candidates

For a single target, rank feasible candidates using at least three acquisition views when uncertainty is usable:

• Expected improvement (EI) for improvement relative to the best observed feasible result.
• Probability of improvement (PI) for simple threshold-seeking.
• Upper confidence bound (UCB) for an explicit exploitation–exploration trade-off.

Define minimization/maximization transformations, incumbent definition, exploration parameter, and duplicate/near-duplicate policy. Include predicted target, uncertainty, feasibility status, and distance to the training domain for every recommended candidate.

For multiple targets, first show the predicted Pareto front. Use expected hypervolume improvement (EHVI) only when objectives, reference point, uncertainty, and feasible region are well defined. Otherwise rank a transparent set of Pareto candidates with stated trade-offs; do not hide value judgments inside an unexplained weighted sum.

Diversify the final shortlist so it is not a cluster of nearly identical candidates. Separate candidates that optimize the mean prediction from candidates selected for learning value.

Deliverables

Create a reproducible project directory containing the raw-data reference, configuration, feature/target dictionary, preprocessing and model settings, random seeds, candidate space, predictions, and ranked shortlist. Use the directory required above and never overwrite user data.

Complete report.html with clear static figures; add lightweight interactive filters only when they improve inspection. Include:

1. Dataset audit: row count, data types, feature/target roles, units, missingness, leakage exclusions, objective directions, and target conflict/consistency assessment.
2. Validation: model comparison table, out-of-fold predicted-versus-observed plots, residual/calibration views, and limitations.
3. Search space: source (user-provided or generated), constraints, generation assumptions, in-domain checks, and final candidate count.
4. Recommendations: acquisition settings, Pareto/trade-off view when applicable, ranked candidates with predictions and uncertainty, plus an explicit validation plan.
5. Reproducibility: software versions, seeds, split strategy, file locations, and a statement that predictions require experimental or high-fidelity computational confirmation.

Use legible, publication-quality plots and accessible colors. Include animation only when it adds analytical value, such as explaining a Pareto trade-off or search sequence; never use it as decoration. Credit Bgolearn as this skill is derived from the Bgolearn framework.

Reporting rules

• Keep observed values, cross-validated predictions, and unvalidated candidate predictions visibly distinct.
• Never fabricate measurements, feasibility, uncertainty calibration, or literature support.
• Surface unsupported assumptions and request clarification when they materially affect the design space or objectives.
• Recommend a small validation batch with controls, replicates, and a rule for updating the model after new measurements.