D4CMPP2 0.4.0__tar.gz

d4cmpp2-0.4.0/D4CMPP2.egg-info/PKG-INFO

@@ -0,0 +1,420 @@
+Metadata-Version: 2.4
+Name: D4CMPP2
+Version: 0.4.0
+Summary: PyTorch Geometric molecular property prediction models
+License-Expression: MIT
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch<3,>=2.2
+Requires-Dist: torch-geometric<3,>=2.8
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: tqdm>=4.65
+Requires-Dist: prettytable>=3.9
+Requires-Dist: rdkit>=2023.9
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: Pillow>=10
+Requires-Dist: PyYAML>=6
+Requires-Dist: MoleculeSculptor<2,>=1.0.1
+Provides-Extra: notebook
+Requires-Dist: jupyterlab>=4; extra == "notebook"
+Requires-Dist: ipywidgets>=8; extra == "notebook"
+Dynamic: license-file
+
+# D4CMPP2
+
+D4CMPP2 is a PyTorch Geometric package for molecular-property regression. It
+supports ordinary molecular graphs, compound/solvent pairs, and interpretable
+ISA models through one training and inference API.
+
+## Requirements and installation
+
+Supported runtime:
+
+- Python 3.10-3.12
+- PyTorch `>=2.2,<3`
+- PyTorch Geometric `>=2.8,<3`
+- Linux and Windows
+- CPU, or CUDA with a matching PyTorch build
+
+Install the appropriate PyTorch build for the machine first, then install
+D4CMPP2:
+
+```sh
+python -m pip install D4CMPP2
+```
+
+Notebook extras are optional:
+
+```sh
+python -m pip install "D4CMPP2[notebook]"
+```
+
+DGL is not installed or loaded. DGL graph caches cannot be renamed or reused
+as PyG caches.
+
+## Supported models
+
+| Family | Network IDs |
+|---|---|
+| General | `GCN`, `MPNN`, `DMPNN`, `AFP`, `GAT` |
+| With solvent | `GCNwS`, `MPNNwS`, `DMPNNwS`, `AFPwS`, `GATwS` |
+| ISA | `GC`, `ISAT`, `ISATPN` |
+
+`AGC`, `MegNet`, `MegNetwS`, `ALIGNN`, and `ALIGNNwS` are not part of the
+PyG-only release.
+
+## Input data
+
+A general model needs a `compound` SMILES column and one or more numeric target
+columns. A `wS` model additionally needs a `solvent` SMILES column:
+
+```csv
+compound,solvent,Solubility
+CCO,O,-0.31
+CCN,CO,-0.18
+```
+
+Useful optional columns and arguments:
+
+- `set`: predefined `train`, `val`, and `test` labels.
+- `numeric_input_columns`: additional finite numeric model inputs.
+- `molecule_columns`: molecule columns in their model input order.
+- `explicit_h_columns`: molecule columns that require explicit hydrogens.
+
+Without a `set` column, the default split is a seeded 80/10/10 random split.
+Invalid SMILES, missing columns, non-numeric inputs, all-NaN targets, and
+misaligned arrays fail with the affected path, column, value, or row.
+
+## Quickstart
+
+The package includes a small `test.csv`. Run a two-epoch CPU smoke training:
+
+```sh
+d4cmpp2 --data test --target Abs --network GCN --device cpu --epoch 2
+```
+
+Equivalent Python:
+
+```python
+from D4CMPP2 import train
+
+model_path = train(
+    data="test",
+    target=["Abs"],
+    network="GCN",
+    device="cpu",
+    max_epoch=2,
+    batch_size=4,
+)
+print(model_path)
+```
+
+Runnable examples for training, solvent and ISA models, saved-model modes,
+inference, uncertainty, optimization, callbacks, custom networks, and the CLI
+are indexed in [`examples/README.md`](examples/README.md).
+
+For GPU training, use `device="cuda:0"` or `--device cuda:0`. D4CMPP2 validates
+the requested index and does not silently fall back to CPU.
+
+### Solvent and ISA
+
+```python
+from D4CMPP2 import train
+
+solvent_model = train(
+    data="solvent_data.csv",
+    target=["Solubility"],
+    network="GCNwS",
+    molecule_columns=["compound", "solvent"],
+    device="cpu",
+)
+
+isa_model = train(
+    data="Aqsoldb",
+    target=["Solubility"],
+    network="ISATPN",
+    sculptor_index=(6, 2, 0),
+    device="cpu",
+)
+```
+
+`sculptor_index=(split, combine, absorb)` controls ISA fragmentation. Existing
+fragment rules and saved `functional_group.csv` files are part of the model
+contract.
+
+## Training behavior
+
+The most important defaults are:
+
+| Key | Default |
+|---|---|
+| `batch_size` | `256` |
+| `max_epoch` | `2000` |
+| `optimizer` | `"Adam"` |
+| `learning_rate` | `0.001` |
+| `weight_decay` | `0.0005` |
+| `device` | `"cuda:0"` |
+| `scaler` | `"standard"` |
+| `verbose` | `True` |
+
+Configuration is resolved into an isolated working copy. Historical precedence
+is retained for numerical compatibility:
+
+| Mode | Lower to higher precedence |
+|---|---|
+| Scratch | defaults, API/CLI, registry |
+| Full resume | saved config, explicit resume overrides |
+| `LOAD_PATH` continue | saved config, current defaults/API |
+| Transfer | source config, current defaults/API, registry |
+| Optimization trial | resolved base, trial values |
+
+Unknown keys remain available to legacy configs and custom implementations.
+Resolved provenance is written to the run manifest without changing
+`config.yaml`.
+
+### Splitting and reproducibility
+
+`split_strategy` accepts:
+
+- `"auto"`: use `set` when present, otherwise random 80/10/10.
+- `"random"`: always use row-level random splitting.
+- `"predefined"`: require the `set` column.
+- `"scaffold"`: keep RDKit Murcko-scaffold groups within one split.
+
+Normal runs write `split_report.json` and `split_assignments.csv`.
+
+```python
+model_path = train(
+    data="Aqsoldb",
+    target=["Solubility"],
+    network="GCN",
+    random_seed=42,
+    split_random_seed=42,
+    deterministic_algorithms=True,
+    device="cpu",
+)
+```
+
+`random_seed` controls Python, NumPy, torch/CUDA, shuffle, DataLoader workers,
+dropout, and partial-training selection. `split_random_seed` controls only the
+data split. Deterministic algorithms may reduce GPU performance or reject an
+unsupported operation.
+
+### Resume, continue, and transfer
+
+The three saved-model modes are mutually exclusive:
+
+- `RESUME_PATH` or `--resume`: exact full-state resume from
+  `checkpoints/latest.ckpt`.
+- `LOAD_PATH` or `--load`: load `final.pth` but reset optimizer, schedulers,
+  epoch, and RNG.
+- `TRANSFER_PATH` or `--transfer`: copy compatible same-name/same-shape
+  parameters into a new model.
+
+Full checkpoints preserve optimizer, both schedulers, epoch, best metric,
+early-stopping state, and RNG state. Transfer writes `transfer_report.json`
+with loaded and skipped parameters plus the source weight hash.
+
+### Outputs and caches
+
+Training returns the model directory, normally below `./_Models/`. Important
+artifacts include:
+
+- `config.yaml`, `network.py`, `final.pth`, `scaler.pkl`
+- `network_identity.json`, `model_summary.txt`
+- `checkpoints/latest.ckpt`, `checkpoints/best.ckpt`
+- `runs/<run_id>/run_manifest.json`
+- `result/prediction.csv`, metrics, curves, and plots
+- data-quality and split reports
+
+Graph caches are atomic, fingerprinted PyG schema-v2 files. Identity includes
+ordered SMILES, feature dimensions, explicit-hydrogen settings, and ISA rules.
+The cache policies are:
+
+- `"v2"`: validate the current cache and fail clearly if it is incompatible.
+- `"regenerate"`: rebuild an invalid v2 cache from the source CSV.
+- `"legacy"`: explicitly load a compatible PyG v1 cache with a warning.
+
+DGL caches are preserved but never loaded.
+
+## Prediction and analysis
+
+```python
+from D4CMPP2 import Analyzer
+
+analyzer = Analyzer(model_path, device="cpu", save_result=False)
+print(analyzer.predict(["CCO", "CCN"]))
+```
+
+`Analyzer` reads the saved config and selects the general, solvent, or ISA
+implementation. It requires `config.yaml`, `network.py`, and `final.pth`;
+non-identity scaling also requires `scaler.pkl`, and ISA requires the saved
+`functional_group.csv`. Load pickle-based artifacts only from trusted model
+folders.
+
+Use row-preserving inference when duplicates or invalid inputs matter:
+
+```python
+result = analyzer.predict_rows(
+    compound=["CCO", "CCO", "not-a-smiles"],
+)
+print(result.to_dataframe())
+```
+
+Every row retains its original index, inputs, prediction, status, and error.
+Solvent and numeric-input models require every saved input column with equal
+length:
+
+```python
+result = analyzer.predict_rows(
+    compound=["CCO", "CCN"],
+    solvent=["O", "CO"],
+    temperature=[298.0, 310.0],
+)
+```
+
+CSV inference preserves source rows and commits the output atomically:
+
+```python
+output_path = analyzer.predict_csv(
+    "molecules.csv",
+    "molecules_prediction.csv",
+    uncertainty_samples=30,
+    uncertainty_seed=42,
+)
+```
+
+`predict_uncertainty()` uses MC dropout and `Analyzer.predict_ensemble()` uses
+compatible independently trained models. Their standard deviations are model
+dispersion estimates, not calibrated prediction intervals.
+
+ISA analyzers also provide `analyze_rows()` and `plot_analysis()`. Fragment
+indices are validated against atom alignment before scores or features are
+returned.
+
+## Experiment comparison and optimization
+
+```python
+from D4CMPP2 import compare_experiments
+
+leaderboard = compare_experiments(
+    ["./_Models"],
+    output_path="leaderboard.csv",
+    metric="val_rmse",
+)
+```
+
+Ranking is calculated separately per target. Legacy, failed, and interrupted
+runs remain visible without borrowing another run's metrics.
+
+For new hyperparameter searches, use the model-aware API:
+
+```python
+import D4CMPP2
+
+result = D4CMPP2.optimize(
+    data="Aqsoldb.csv",
+    target=["Solubility"],
+    network="GCN",
+    HP=["hidden_dim", "dropout"],
+    optimize_strategy="bayesian",
+    n_trials=20,
+    device="cpu",
+)
+print(result.best_params, result.best_model_path)
+```
+
+`HP=None` uses the model's default optimization space. A key list uses declared
+model ranges; a dictionary supplies categorical values or numeric ranges.
+Supported strategies are `"bayesian"` and `"grid"`. Atomic JSON/CSV summaries
+and trial directories allow compatible searches to resume.
+
+The legacy `grid_search()` API remains available with its historical `None`
+return value and continue-on-trial-error behavior.
+
+## Callbacks and custom networks
+
+Observation-only training callbacks are runtime objects and are not saved:
+
+```python
+from D4CMPP2 import train
+from D4CMPP2.src.TrainManager.callbacks import EventHistory
+
+history = EventHistory()
+model_path = train(
+    data="test",
+    target=["Abs"],
+    network="GCN",
+    device="cpu",
+    callbacks=[history],
+)
+```
+
+Callbacks receive immutable run/epoch/validation/checkpoint/error events. A
+callback failure stops training and preserves the original failure contract.
+
+Custom models subclass `D4CMPP2.MolecularNetwork`, declare `model_name`,
+`input_contract`, hyperparameters, and optionally `compute_loss()`, then call:
+
+```python
+D4CMPP2.register_network(CustomGCN, data_contract="molecule")
+```
+
+Available data contracts are `"molecule"`, `"solvent"`, and `"isa"`. Define
+the class at module scope in an importable file. Training copies that source to
+the model directory as `network.py`; reload and transfer prefer the saved
+snapshot. See `examples/custom_network.py` for a complete implementation.
+
+## CLI
+
+```sh
+python -m D4CMPP2 --help
+d4cmpp2 --help
+```
+
+Target columns are comma-separated. `--quiet` hides routine information and
+progress but not warnings or errors. `--cuda 0` remains a deprecated alias for
+`--device cuda:0`.
+
+## Migration and compatibility
+
+- Public `train`, `grid_search`, `Analyzer`, `Segmentator`, and `Data` names
+  remain available.
+- New runs fit the target scaler on training rows by default. Old configs
+  without the policy retain historical full-data scaling with a warning.
+- The loader prefers the saved model folder's `network.py`, config, weights,
+  scaler, and ISA rules over obsolete absolute paths.
+- The historical `ISATPM` saved name is supported through the `ISATPN`
+  compatibility adapter.
+- Keep DGL-era models and caches with their original environment for archival
+  reproduction. Automatic conversion is not provided.
+- Package version and saved-model/config contract version are separate.
+
+Public API or saved-asset compatibility breaks require a major release.
+Deprecations should include a warning and a migration path.
+
+## Troubleshooting
+
+- `torch_geometric` import failure: install torch and PyG builds compatible
+  with the same Python and CPU/CUDA runtime.
+- CUDA unavailable or index out of range: select an existing `cuda:N` or use
+  `device="cpu"` explicitly.
+- Missing target/SMILES column: compare the reported available columns with the
+  configured target and molecule columns.
+- Invalid SMILES: fix or remove the reported rows; related arrays share one
+  alignment mask.
+- Cache shape or recipe mismatch: use the source CSV with
+  `graph_cache_policy="regenerate"` after reviewing the diagnostic.
+- Model path missing or ambiguous: pass the exact saved-model directory.
+- Old model fails to load: preserve the complete folder and original
+  environment; report config, package versions, and the error without sharing
+  private data.
+
+## Repository maintenance
+
+Implementation contracts, compatibility constraints, validation commands, and
+change notes live in the nearest `AGENTS.md` file within each source area.
+Read the workspace and nearest folder instructions before modifying code.

d4cmpp2-0.4.0/D4CMPP2.egg-info/SOURCES.txt

@@ -0,0 +1,273 @@
+LICENSE
+MANIFEST.in
+README.md
+__init__.py
+__main__.py
+_main.py
+cli.py
+exceptions.py
+grid_search.py
+network_refer.yaml
+optimize.py
+pyproject.toml
+./__init__.py
+./__main__.py
+./_main.py
+./cli.py
+./exceptions.py
+./grid_search.py
+./network_refer.yaml
+./optimize.py
+./_Data/AGENTS.md
+./_Data/Aqsoldb.csv
+./_Data/BradleyMP.csv
+./_Data/Lipophilicity.csv
+./_Data/README.md
+./_Data/__init__.py
+./_Data/optical.csv
+./_Data/test.csv
+./networks/AFP_model.py
+./networks/AFPwithSolv_model.py
+./networks/DMPNN_model.py
+./networks/DMPNNwithSolv_model.py
+./networks/GAT_model.py
+./networks/GATwithSolv_model.py
+./networks/GCN_model.py
+./networks/GCNwithSolv_model.py
+./networks/GC_model.py
+./networks/ISATPM_model.py
+./networks/ISATPN_model.py
+./networks/ISAT_model.py
+./networks/MPNN_model.py
+./networks/MPNNwithSolv_model.py
+./networks/__init__.py
+./networks/base.py
+./networks/registry.py
+./networks/src/AFP.py
+./networks/src/BiDropout.py
+./networks/src/DMPNN.py
+./networks/src/GAT.py
+./networks/src/GC.py
+./networks/src/GCN.py
+./networks/src/ISAT.py
+./networks/src/Linear.py
+./networks/src/MPNN.py
+./networks/src/SolventLayer.py
+./networks/src/__init__.py
+./networks/src/distGCN.py
+./networks/src/pyg_hetero.py
+./src/PostProcessor.py
+./src/__init__.py
+./src/Analyzer/ISAAnalyzer.py
+./src/Analyzer/ISAPNAnalyzer.py
+./src/Analyzer/ISAwSAnalyzer.py
+./src/Analyzer/MolAnalyzer.py
+./src/Analyzer/__init__.py
+./src/Analyzer/core.py
+./src/Analyzer/factory.py
+./src/Analyzer/interpretation.py
+./src/Analyzer/results.py
+./src/DataManager/ISADataManager.py
+./src/DataManager/MolDataManager.py
+./src/DataManager/__init__.py
+./src/DataManager/contracts.py
+./src/DataManager/Dataset/GraphDataset.py
+./src/DataManager/Dataset/ISAGraphDataset.py
+./src/DataManager/Dataset/__init__.py
+./src/DataManager/GraphGenerator/ISAGraphGenerator.py
+./src/DataManager/GraphGenerator/MolGraphGenerator.py
+./src/DataManager/GraphGenerator/__init__.py
+./src/NetworkManager/ISANetworkManager.py
+./src/NetworkManager/NetworkManager.py
+./src/NetworkManager/__init__.py
+./src/TrainManager/ISATrainManager.py
+./src/TrainManager/TrainManager.py
+./src/TrainManager/__init__.py
+./src/TrainManager/callbacks.py
+./src/utils/PATH.py
+./src/utils/__init__.py
+./src/utils/argparser.py
+./src/utils/checkpointing.py
+./src/utils/config_resolution.py
+./src/utils/config_validation.py
+./src/utils/csv_validation.py
+./src/utils/data_quality.py
+./src/utils/featureizer.py
+./src/utils/functional_group.csv
+./src/utils/graph_cache.py
+./src/utils/leaderboard.py
+./src/utils/metrics.py
+./src/utils/module_loader.py
+./src/utils/output.py
+./src/utils/reproducibility.py
+./src/utils/run_manifest.py
+./src/utils/scaler.py
+./src/utils/sculptor.py
+./src/utils/splitting.py
+./src/utils/supportfile_saver.py
+./src/utils/tools.py
+./src/utils/transfer_learning.py
+D4CMPP2.egg-info/PKG-INFO
+D4CMPP2.egg-info/SOURCES.txt
+D4CMPP2.egg-info/dependency_links.txt
+D4CMPP2.egg-info/entry_points.txt
+D4CMPP2.egg-info/requires.txt
+D4CMPP2.egg-info/top_level.txt
+_Data/AGENTS.md
+_Data/Aqsoldb.csv
+_Data/BradleyMP.csv
+_Data/Lipophilicity.csv
+_Data/README.md
+_Data/__init__.py
+_Data/optical.csv
+_Data/test.csv
+examples/AGENTS.md
+examples/README.md
+examples/custom_network.py
+examples/ISA/segment.py
+examples/assets/tiny_numeric.csv
+examples/cli/README.md
+examples/experiments/01_compare.py
+examples/experiments/02_optimize.py
+examples/experiments/03_legacy_grid_search.py
+examples/extensions/01_callbacks.py
+examples/extensions/02_custom_network_training.py
+examples/extensions/03_numeric_inputs.py
+examples/inference/01_prediction.py
+examples/inference/02_csv_prediction.py
+examples/inference/03_uncertainty_ensemble.py
+examples/inference/04_isa_interpretation.py
+examples/training/01_basic_cpu.py
+examples/training/02_solvent.py
+examples/training/03_multitarget.py
+examples/training/04_splitting_reproducibility.py
+examples/training/05_isa.py
+examples/training/06_saved_model_modes.py
+examples/training/07_model_families.py
+networks/AFP_model.py
+networks/AFPwithSolv_model.py
+networks/DMPNN_model.py
+networks/DMPNNwithSolv_model.py
+networks/GAT_model.py
+networks/GATwithSolv_model.py
+networks/GCN_model.py
+networks/GCNwithSolv_model.py
+networks/GC_model.py
+networks/ISATPM_model.py
+networks/ISATPN_model.py
+networks/ISAT_model.py
+networks/MPNN_model.py
+networks/MPNNwithSolv_model.py
+networks/__init__.py
+networks/base.py
+networks/registry.py
+networks/src/AFP.py
+networks/src/BiDropout.py
+networks/src/DMPNN.py
+networks/src/GAT.py
+networks/src/GC.py
+networks/src/GCN.py
+networks/src/ISAT.py
+networks/src/Linear.py
+networks/src/MPNN.py
+networks/src/SolventLayer.py
+networks/src/__init__.py
+networks/src/distGCN.py
+networks/src/pyg_hetero.py
+src/PostProcessor.py
+src/__init__.py
+src/Analyzer/ISAAnalyzer.py
+src/Analyzer/ISAPNAnalyzer.py
+src/Analyzer/ISAwSAnalyzer.py
+src/Analyzer/MolAnalyzer.py
+src/Analyzer/__init__.py
+src/Analyzer/core.py
+src/Analyzer/factory.py
+src/Analyzer/interpretation.py
+src/Analyzer/results.py
+src/DataManager/ISADataManager.py
+src/DataManager/MolDataManager.py
+src/DataManager/__init__.py
+src/DataManager/contracts.py
+src/DataManager/Dataset/GraphDataset.py
+src/DataManager/Dataset/ISAGraphDataset.py
+src/DataManager/Dataset/__init__.py
+src/DataManager/GraphGenerator/ISAGraphGenerator.py
+src/DataManager/GraphGenerator/MolGraphGenerator.py
+src/DataManager/GraphGenerator/__init__.py
+src/NetworkManager/ISANetworkManager.py
+src/NetworkManager/NetworkManager.py
+src/NetworkManager/__init__.py
+src/TrainManager/ISATrainManager.py
+src/TrainManager/TrainManager.py
+src/TrainManager/__init__.py
+src/TrainManager/callbacks.py
+src/utils/PATH.py
+src/utils/__init__.py
+src/utils/argparser.py
+src/utils/checkpointing.py
+src/utils/config_resolution.py
+src/utils/config_validation.py
+src/utils/csv_validation.py
+src/utils/data_quality.py
+src/utils/featureizer.py
+src/utils/functional_group.csv
+src/utils/graph_cache.py
+src/utils/leaderboard.py
+src/utils/metrics.py
+src/utils/module_loader.py
+src/utils/output.py
+src/utils/reproducibility.py
+src/utils/run_manifest.py
+src/utils/scaler.py
+src/utils/sculptor.py
+src/utils/splitting.py
+src/utils/supportfile_saver.py
+src/utils/tools.py
+src/utils/transfer_learning.py
+tests/test_cli_packaging.py
+tests/test_config_validation.py
+tests/test_csv_data_manager_validation.py
+tests/test_csv_validation.py
+tests/test_custom_network.py
+tests/test_data_fixture.py
+tests/test_example_model_compatibility.py
+tests/test_examples_syntax.py
+tests/test_failure_behavior.py
+tests/test_failure_contracts.py
+tests/test_gcn_end_to_end.py
+tests/test_graph_alignment.py
+tests/test_heavy_smoke.py
+tests/test_network_abc.py
+tests/test_network_persistence.py
+tests/test_optimize.py
+tests/test_path_utils.py
+tests/test_public_contracts.py
+tests/test_pyg_data_contract.py
+tests/test_pyg_dmpnn_afp.py
+tests/test_pyg_gcn.py
+tests/test_pyg_isa_models.py
+tests/test_pyg_mpnn_gat.py
+tests/test_runtime_environment.py
+tests/test_scaler_alignment.py
+tests/test_state_dict_contract.py
+tests/test_t3_checkpoint_policy.py
+tests/test_t3_data_quality.py
+tests/test_t3_dataset_contract_matrix.py
+tests/test_t3_graph_cache_integrity.py
+tests/test_t3_grid_search.py
+tests/test_t3_leaderboard.py
+tests/test_t3_registry_smoke_matrix.py
+tests/test_t3_reproducibility.py
+tests/test_t3_run_manifest.py
+tests/test_t3_scaffold_split.py
+tests/test_t3_transfer_learning.py
+tests/test_t4_analyzer_core.py
+tests/test_t5_callbacks.py
+tests/test_t5_config_resolution.py
+tests/test_t5_errors_logging.py
+tests/test_t5_import_discovery.py
+tests/test_t5_manager_contracts.py
+tests/test_t5_verbose_output.py
+tests/test_t6_ci_contract.py
+tests/test_t7_cycle_audit.py

d4cmpp2-0.4.0/D4CMPP2.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

d4cmpp2-0.4.0/D4CMPP2.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+d4cmpp2 = D4CMPP2.cli:main