matsieve 0.1.0

======================================================================

matsieve

======================================================================

An uncertainty-aware, objective-driven screening pipeline for materials

discovery.



matsieve takes a training set of materials with a known property and a

pool of candidate materials, and screens the candidates down to a

shortlist likely to have the property you want — with a calibrated

uncertainty attached to every prediction. It generalizes a band-gap

perovskite workflow into a tool for *any* material and *any* scalar

target property.



The name is the metaphor: candidates fall through progressively finer

sieves (featurize -> select -> classify -> regress -> screen) until only

the promising ones remain.





----------------------------------------------------------------------

WHAT MAKES IT DIFFERENT

----------------------------------------------------------------------

* Uncertainty on every prediction. Classification returns a *calibrated*

  probability (not a hand-made confidence) plus a conformal prediction

  set; regression returns a conformal prediction interval [lo, hi] plus

  an ensemble-disagreement standard deviation. In materials science a

  bare predicted number is rarely enough — matsieve never gives you one

  without a measure of how much to trust it.



* Four screening objectives, chosen in the parameters file:

    - window     : keep candidates whose property lands in [min, max]

    - threshold  : keep candidates above (or below) a cutoff

    - min / max  : rank all candidates and return the best top-N



* Any property, any material. Nothing is hard-coded to band gap. Point

  it at formation energy, a dielectric constant, a figure of merit —

  whatever your column 2 contains.



* Bring your own features. Add material-specific columns to the training

  and candidate files; choose whether they pass through feature

  selection or bypass it and are always kept.



* CPU or GPU. Gradient-boosting models (XGBoost/LightGBM/CatBoost) run on

  GPU when you ask for it and a usable one is present, with automatic,

  per-library fallback to CPU. Everything else is CPU.



* One command, organized output. Drop two CSVs, edit parameters.txt,

  run. Every stage writes into its own numbered folder under a

  timestamped run directory, and the full console log is saved to disk.





----------------------------------------------------------------------

INSTALLATION

----------------------------------------------------------------------

Requires Python 3.11+.



From source (recommended while iterating):

    pip install -e .



Or reproduce the exact tested environment:

    pip install -r requirements.txt

    pip install -e .



Or with conda:

    conda env create -f environment.yml

    conda activate matsieve



The CBFV element-property tables ship inside the package; no extra data

files are needed.





----------------------------------------------------------------------

INPUT FILE FORMAT

----------------------------------------------------------------------

Two CSV files.



Training file (default name Main_dataset.csv):

    column 1        : chemical formula / structure identifier

    column 2        : the target property (numeric)

    columns 3+      : OPTIONAL custom features (any numeric columns)



    Example header:  Structure,bandgap,tau,miu,miu_mis



Candidate file (default name Candidate_dataset.csv):

    column 1        : chemical formula / structure identifier

    other columns   : the SAME custom-feature headers as the training

                      file (order may differ; names must match)



    Example header:  structure,tau,miu,miu_mis



If you have no custom features, just provide the identifier (+ target)

columns. The identifier column header may differ in case between the two

files; only its position (column 1) matters.





----------------------------------------------------------------------

QUICK START

----------------------------------------------------------------------

1. Put Main_dataset.csv and Candidate_dataset.csv in a working folder.

2. Copy examples/parameters.txt into that folder and edit it. At minimum

   set target_name and the screening objective; the [ADVANCED] section

   can be left at its defaults.

3. Sanity-check the configuration (fast, trains nothing):

       matsieve validate --config parameters.txt

4. Run the whole pipeline:

       matsieve run --config parameters.txt



Results appear under outputs/run_<timestamp>/ and outputs/latest points

at the most recent run.





----------------------------------------------------------------------

OUTPUT LAYOUT

----------------------------------------------------------------------

outputs/run_<timestamp>/

    parameters_used.txt              exact config used (reproducibility)

    logs/run.log                     full console log of the run

    01_featurization/                featurized training + candidates

    02_feature_selection/            selected_features.csv (the manifest),

                                     filtered_training_data.csv, report

    03_classification/

        threshold_<value>/           one folder per boundary classifier:

                                     best_model.joblib, metrics, metadata,

                                     plots/

    04_regression/                   best_model.joblib, per-model results,

                                     ensemble results, models/, plots/

    05_screening/

        candidate_classified_*.csv   per-threshold class + probability +

                                     confidence + conformal set

        candidate_<target>_predicted.csv

                                     value + interval + ensemble std

        screened_candidates.csv      survivors of the objective screen

        final_candidates.csv         survivors of the final tightened screen

    reports/summary.txt              human-readable digest





----------------------------------------------------------------------

COMMANDS

----------------------------------------------------------------------

    matsieve run       --config parameters.txt [--output-dir DIR]

                                               [--input-dir DIR]

    matsieve validate  --config parameters.txt

    matsieve --version



--input-dir is where the input CSVs live (default: current directory).

--output-dir is the root for run folders (default: outputs).





----------------------------------------------------------------------

FURTHER READING

----------------------------------------------------------------------

    docs/PARAMETERS.txt   every parameter, its type, default, and meaning

                          (auto-generated from the code, always in sync)

    docs/WORKFLOW.txt     what each of the eight stages does and the

                          science behind them





----------------------------------------------------------------------

NOTES

----------------------------------------------------------------------

* Reproducibility: a fixed random_state (default 42) governs splits,

  model seeds, and cross-validation.

* Large candidate sets: candidates are featurized and scored in streamed

  chunks (candidate_chunk_size), so memory stays bounded from one

  candidate to millions.

* Interval coverage is reported per run; if empirical coverage on the

  test set drifts far from your uq_confidence target, treat the model

  as under-trained (raise n_trials, add data) rather than trusting the

  intervals blindly.