Metadata-Version: 2.4
Name: matsieve
Version: 0.1.0
Summary: Uncertainty-aware, objective-driven screening pipeline for materials discovery
Author-email: Woshitha Sasindu Hinget <wshinget@gmail.com>
Maintainer-email: WS Hinget <wshinget@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Woshitha/matsieve
Project-URL: Repository, https://github.com/Woshitha/matsieve
Project-URL: Issues, https://github.com/Woshitha/matsieve/issues
Keywords: materials-science,machine-learning,screening,uncertainty-quantification,conformal-prediction,CBFV
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/plain
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.11
Requires-Dist: scikit-learn>=1.3
Requires-Dist: joblib>=1.3
Requires-Dist: matplotlib>=3.7
Requires-Dist: tqdm>=4.65
Requires-Dist: dcor>=0.6
Requires-Dist: lightgbm>=4.0
Requires-Dist: xgboost>=2.0
Requires-Dist: catboost>=1.2
Requires-Dist: imbalanced-learn>=0.11
Requires-Dist: mapie>=1.4
Requires-Dist: optuna>=3.4
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

======================================================================
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.
