{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Pedon Package Structure\n",
    "\n",
    "*Martin Vonk (2025)*\n",
    "\n",
    "## Overview\n",
    "\n",
    "`pedon` is a Python package for analyzing unsaturated soil hydraulic properties. It provides an integrated framework that combines:\n",
    "\n",
    "1. **Soil Hydraulic Models** - parametric descriptions of water retention and conductivity\n",
    "2. **Parameter Databases** - pre-computed parameters from established sources (HYDRUS, VS2D, Staring)\n",
    "3. **Pedotransfer Functions** - empirical relationships to estimate parameters from easily measured soil properties\n",
    "4. **Fitting Routines** - direct parameter estimation from laboratory measurements\n",
    "\n",
    "This notebook introduces the three core classes that form the foundation of `pedon`: `Soil`, `SoilModel`, and `SoilSample`.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import inspect\n",
    "import sys\n",
    "\n",
    "import pedon as pe"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Three Core Classes\n",
    "\n",
    "`pedon` is built around three main classes:\n",
    "\n",
    "1. **`SoilModel`** - represents a soil hydraulic model (e.g., van Genuchten, Brooks-Corey)\n",
    "2. **`SoilSample`** - holds measured or estimated soil properties (e.g., grain size, water content, conductivity)\n",
    "3. **`Soil`** - combines a `SoilModel` with metadata (name, source, description)\n",
    "\n",
    "### Exploring the Soil Class\n",
    "\n",
    "The `Soil` class is the primary container for soil hydraulic information. Its attributes are:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': str,\n",
       " 'model': pedon.soilmodel.SoilModel | None,\n",
       " 'sample': pedon.soil.SoilSample | None,\n",
       " 'source': str | None,\n",
       " 'description': str | None}"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# main class\n",
    "# containing both SoilModel and SoilSample\n",
    "pe.Soil.__annotations__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Available Soil Models\n",
    "\n",
    "`pedon` provides multiple soil model formulations from the literature. Each model represents the relationship between pressure head (h), water content (θ), and hydraulic conductivity (K):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Brooks',\n",
       " 'Fredlund',\n",
       " 'Gardner',\n",
       " 'Genuchten',\n",
       " 'GenuchtenGardner',\n",
       " 'Haverkamp',\n",
       " 'Panday',\n",
       " 'Protocol',\n",
       " 'Rucker',\n",
       " 'SoilModel']"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# classes for soil models\n",
    "soilmodels = [\n",
    "    cls_name\n",
    "    for cls_name, cls_obj in inspect.getmembers(sys.modules[\"pedon.soilmodel\"])\n",
    "    if inspect.isclass(cls_obj)\n",
    "]\n",
    "soilmodels"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The SoilSample Class\n",
    "\n",
    "The `SoilSample` class stores measured or observable soil properties. It can contain:\n",
    "\n",
    "**From soil composition:**\n",
    "- `sand_p`, `silt_p`, `clay_p` - grain size distribution (%)\n",
    "- `rho` - bulk density (g/cm³)\n",
    "- `om_p` - organic matter content (%)\n",
    "- `m50` - median sand grain diameter (μm)\n",
    "\n",
    "**From direct measurements (laboratory or field):**\n",
    "- `h` - pressure head values (cm)\n",
    "- `theta` - corresponding water content measurements (-)\n",
    "- `k` - corresponding hydraulic conductivity measurements (cm/d or m/s)\n",
    "\n",
    "The `SoilSample` can be used with various functions to estimate soil hydraulic parameters through pedotransfer functions or curve fitting."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "SoilSample attributes:\n",
      "  sand_p: float | None\n",
      "  silt_p: float | None\n",
      "  clay_p: float | None\n",
      "  rho: float | None\n",
      "  th33: float | None\n",
      "  th1500: float | None\n",
      "  om_p: float | None\n",
      "  m50: float | None\n",
      "  d10: float | None\n",
      "  d20: float | None\n",
      "  h: numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[numpy.float64]] | None\n",
      "  k: numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[numpy.float64]] | None\n",
      "  theta: numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[numpy.float64]] | None\n"
     ]
    }
   ],
   "source": [
    "# Show all attributes of SoilSample class\n",
    "print(\"SoilSample attributes:\")\n",
    "for attr, dtype in pe.SoilSample.__annotations__.items():\n",
    "    print(f\"  {attr}: {dtype}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Workflow Overview\n",
    "\n",
    "The typical workflow in `pedon` could follow this pattern:\n",
    "\n",
    "1. **Create a `SoilSample`** - from measured properties or existing data\n",
    "2. **Estimate parameters** - using pedotransfer functions, HYPAGS, or other methods\n",
    "3. **Get a `SoilModel`** - with parameters that describe water retention and conductivity\n",
    "4. **Use the model** - evaluate properties at any pressure head, or export to external tools\n",
    "\n",
    "In the following notebooks, you'll learn how to work with each of these components and integrate them into your soil analysis workflows."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "pedon (3.13.5)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.5"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}