Soil Strength Prediction Pipeline

This repository contains an end-to-end machine learning pipeline designed to predict soil strength (Unconfined Compressive Strength, UCS) based on the proportions of soil mixtures and curing properties. The system employs TabPFN, an advanced prior-data fitted network for tabular data, alongside integration with large language and vision models for geotechnical analysis.

Features

• TabPFN-based Modelling: Utilizes meta-learned models (tabpfn) enabling rapid model training and high accuracy on tabular data without extensive hyperparameter tuning.
• Rich Output Console: Provides a visually engaging UI using rich for logs, tables, and progress indicators.
• Expert LLM & Dual-mode VLM Assistance:
  • Generates detailed, natural language explanations of soil strength predictions via SoilExpertLLM.
  • Supports structural evaluation tasks evaluating visual characteristics of soil with SoilVisualVLM via integration with advanced foundation models (InternVL3-78B).

Project Structure

.
├── main.py            # Primary entrypoint wrapping the prediction and evaluation pipeline
├── data_loader.py     # Utilities to load, clean, and partition soil data
├── model_trainer.py   # Handles setup, training, and evaluation of the predictive models
├── llm_reporter.py    # Interfaces with multimodal LLMs for expert geotechnical summaries
├── requirements.txt   # Core Python dependencies
├── data/              # Folder to store CSV and other datastores (ignored via .gitignore)
└── README.md

Setup & Installation

Before analyzing the data, ensure you have Python 3.12+ installed.

We recommend utilizing an isolated virtual environment (.venv):

# 1. Create a Python environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 2. Install Dependencies
pip install -r requirements.txt

Dataset

The system relies on a dataset ideally located at data/raw_soil_data.csv. The main pipeline looks for columns like RH_Percent, GGBFS_Percent, Curing_Days, DFSI_Percent, and targets UCS_kPa.

Usage

Simply trigger the main script from your terminal:

python main.py

This will run the full load, split, train, and validation cycles. In sequence, it will output the train vs. evaluation metrics, process an unseen mixture through the pipeline, and initialize LLM analysis steps.

Requirements

Please see requirements.txt for the explicit package requirements. Major dependencies include pandas, scikit-learn, tabpfn, rich, transformers, torchvision, and accelerate.

License

MIT