geoeq 0.0.1__tar.gz

geoeq-0.0.1/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [0.0.1] - 2026-03-27
+
+### Added
+
+- `geoeq.soil.properties` module with 16 soil phase-relationship functions:
+  - void ratio / porosity conversions
+  - degree of saturation
+  - water content
+  - dry, saturated, bulk, and submerged unit weights
+  - dry and bulk density
+  - void ratio from water content and from dry unit weight
+  - relative density
+  - plasticity index, liquidity index, consistency index
+- `geoeq.core.validation` module with input validation helpers
+- `geoeq.core.constants` module with physical constants (gravity, gamma_w)
+- `geoeq.core.types` module with `Soil` dataclass
+- Test suite with 43 tests covering all public functions
+- MIT license
+- README with installation, usage, API reference, and roadmap

geoeq-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ripon Chandra Malo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geoeq-0.0.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+include CHANGELOG.md

geoeq-0.0.1/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: geoeq
+Version: 0.0.1
+Summary: A Python library for geotechnical engineering calculations.
+Author: Ripon Chandra Malo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/riponcm/geoeq
+Project-URL: Repository, https://github.com/riponcm/geoeq
+Project-URL: Changelog, https://github.com/riponcm/geoeq/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/riponcm/geoeq/issues
+Keywords: geoeq,geotechnical,soil mechanics,civil engineering,geotechnical engineering,soil properties,geotechnical interpretation,geotechnical formulas,bearing capacity,foundation,settlement
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# geoeq
+
+A Python library for geotechnical engineering calculations.
+
+**geoeq** brings common geotechnical formulas into one consistent, validated,
+and well-documented Python package. It is built for engineers, students, and
+researchers who want to replace repetitive spreadsheet work with clean,
+reusable code.
+
+---
+
+## Status
+
+This is **v0.0.1**, the first public release. It covers **soil property and
+phase-relationship formulas** -- the building blocks for everything else in
+geotechnical engineering.
+
+Future releases will add effective stress, bearing capacity, settlement,
+consolidation, earth pressure, slope stability, pile capacity, liquefaction
+assessment, and more.
+
+---
+
+## Installation
+
+```bash
+pip install geoeq
+```
+
+Requires Python 3.9 or later. No external dependencies.
+
+---
+
+## Quick start
+
+```python
+from geoeq.soil import properties as sp
+
+# Dry unit weight from specific gravity and void ratio
+gamma_d = sp.dry_unit_weight(Gs=2.65, e=0.72)
+print(f"Dry unit weight: {gamma_d:.2f} kN/m3")
+
+# Saturated and submerged unit weights
+gamma_sat = sp.saturated_unit_weight(Gs=2.65, e=0.72)
+gamma_sub = sp.submerged_unit_weight(Gs=2.65, e=0.72)
+
+# Phase relations
+n = sp.porosity_from_void_ratio(0.72)
+S = sp.degree_of_saturation(w=0.18, Gs=2.65, e=0.72)
+w = sp.water_content(S=0.80, Gs=2.65, e=0.72)
+e = sp.void_ratio_from_porosity(0.42)
+
+# Relative density
+Dr = sp.relative_density(e=0.60, e_max=0.85, e_min=0.45)
+
+# Atterberg limits
+PI = sp.plasticity_index(LL=48, PL=22)
+LI = sp.liquidity_index(w=35, PL=22, PI=26)
+CI = sp.consistency_index(w=35, LL=48, PI=26)
+```
+
+---
+
+## What is included in v0.0.1
+
+### Soil property and phase-relationship formulas
+
+All functions validate inputs, document units in docstrings, and reference
+their source methods.
+
+**Void ratio and porosity**
+- `void_ratio_from_porosity(n)` -- convert porosity to void ratio
+- `porosity_from_void_ratio(e)` -- convert void ratio to porosity
+
+**Degree of saturation and water content**
+- `degree_of_saturation(w, Gs, e)` -- compute S from water content, Gs, and e
+- `water_content(S, Gs, e)` -- compute w from saturation, Gs, and e
+
+**Unit weights**
+- `dry_unit_weight(Gs, e)` -- dry unit weight (kN/m3)
+- `saturated_unit_weight(Gs, e)` -- saturated unit weight (kN/m3)
+- `bulk_unit_weight(Gs, e, S)` -- moist/total unit weight (kN/m3)
+- `submerged_unit_weight(Gs, e)` -- buoyant unit weight (kN/m3)
+
+**Density**
+- `dry_density(Gs, e)` -- dry density (kg/m3)
+- `bulk_density(Gs, e, S)` -- bulk density (kg/m3)
+
+**Void ratio from other quantities**
+- `void_ratio_from_water_content(w, Gs, S)` -- compute e from w, Gs, S
+- `void_ratio_from_dry_unit_weight(gamma_d, Gs)` -- compute e from gamma_d
+
+**Relative density**
+- `relative_density(e, e_max, e_min)` -- density index for granular soils
+
+**Atterberg limits and consistency**
+- `plasticity_index(LL, PL)` -- PI = LL - PL
+- `liquidity_index(w, PL, PI)` -- LI
+- `consistency_index(w, LL, PI)` -- CI
+
+### Core utilities
+
+- **Validation** -- input checking (positive, non-negative, range, fraction, angle)
+- **Constants** -- gravity, unit weight of water, atmospheric pressure
+- **Types** -- `Soil` dataclass for passing soil properties between functions
+
+---
+
+## Design principles
+
+- **Validated inputs.** Every function checks that values are physically
+  meaningful. Negative void ratios, impossible saturation, and bad angles
+  raise clear errors.
+- **Documented units.** Every docstring states what units are expected and
+  returned.
+- **Traceable methods.** Docstrings reference the source formula or textbook.
+- **No hidden dependencies.** v0.0.1 uses only the Python standard library.
+- **Tested.** Every formula is tested against hand-calculated values and
+  textbook examples.
+
+---
+
+## Roadmap
+
+| Version | Scope |
+|---------|-------|
+| v0.0.1  | Soil properties and phase relations |
+| v0.1.x  | Effective stress, pore pressure, seepage |
+| v0.2.x  | Shallow foundations, bearing capacity, settlement |
+| v0.3.x  | Soil classification (USCS), SPT/CPT correlations |
+| v0.4.x  | Earth pressure, consolidation, slope stability |
+| v0.5.x  | Pile capacity, liquefaction, advanced methods |
+| v1.0.0  | Stable API, full documentation, examples |
+
+---
+
+## Running the tests
+
+From a clone of this repository:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+If you only install pytest, tests still run from the project root (see `pythonpath` in `pyproject.toml`):
+
+```bash
+pip install pytest
+pytest
+```
+
+The wheel on PyPI does not include the test files; run tests from a source checkout.
+
+---
+
+## Contributing
+
+The repository is **private** until around **v0.5**; it will then be opened for
+public contributions. Until then, feedback and feature requests are appreciated.
+
+Every contribution should include the code, a test, a documentation update,
+and a reference for the method.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+Copyright (c) 2026 Ripon Chandra Malo

geoeq-0.0.1/README.md

@@ -0,0 +1,171 @@
+# geoeq
+
+A Python library for geotechnical engineering calculations.
+
+**geoeq** brings common geotechnical formulas into one consistent, validated,
+and well-documented Python package. It is built for engineers, students, and
+researchers who want to replace repetitive spreadsheet work with clean,
+reusable code.
+
+---
+
+## Status
+
+This is **v0.0.1**, the first public release. It covers **soil property and
+phase-relationship formulas** -- the building blocks for everything else in
+geotechnical engineering.
+
+Future releases will add effective stress, bearing capacity, settlement,
+consolidation, earth pressure, slope stability, pile capacity, liquefaction
+assessment, and more.
+
+---
+
+## Installation
+
+```bash
+pip install geoeq
+```
+
+Requires Python 3.9 or later. No external dependencies.
+
+---
+
+## Quick start
+
+```python
+from geoeq.soil import properties as sp
+
+# Dry unit weight from specific gravity and void ratio
+gamma_d = sp.dry_unit_weight(Gs=2.65, e=0.72)
+print(f"Dry unit weight: {gamma_d:.2f} kN/m3")
+
+# Saturated and submerged unit weights
+gamma_sat = sp.saturated_unit_weight(Gs=2.65, e=0.72)
+gamma_sub = sp.submerged_unit_weight(Gs=2.65, e=0.72)
+
+# Phase relations
+n = sp.porosity_from_void_ratio(0.72)
+S = sp.degree_of_saturation(w=0.18, Gs=2.65, e=0.72)
+w = sp.water_content(S=0.80, Gs=2.65, e=0.72)
+e = sp.void_ratio_from_porosity(0.42)
+
+# Relative density
+Dr = sp.relative_density(e=0.60, e_max=0.85, e_min=0.45)
+
+# Atterberg limits
+PI = sp.plasticity_index(LL=48, PL=22)
+LI = sp.liquidity_index(w=35, PL=22, PI=26)
+CI = sp.consistency_index(w=35, LL=48, PI=26)
+```
+
+---
+
+## What is included in v0.0.1
+
+### Soil property and phase-relationship formulas
+
+All functions validate inputs, document units in docstrings, and reference
+their source methods.
+
+**Void ratio and porosity**
+- `void_ratio_from_porosity(n)` -- convert porosity to void ratio
+- `porosity_from_void_ratio(e)` -- convert void ratio to porosity
+
+**Degree of saturation and water content**
+- `degree_of_saturation(w, Gs, e)` -- compute S from water content, Gs, and e
+- `water_content(S, Gs, e)` -- compute w from saturation, Gs, and e
+
+**Unit weights**
+- `dry_unit_weight(Gs, e)` -- dry unit weight (kN/m3)
+- `saturated_unit_weight(Gs, e)` -- saturated unit weight (kN/m3)
+- `bulk_unit_weight(Gs, e, S)` -- moist/total unit weight (kN/m3)
+- `submerged_unit_weight(Gs, e)` -- buoyant unit weight (kN/m3)
+
+**Density**
+- `dry_density(Gs, e)` -- dry density (kg/m3)
+- `bulk_density(Gs, e, S)` -- bulk density (kg/m3)
+
+**Void ratio from other quantities**
+- `void_ratio_from_water_content(w, Gs, S)` -- compute e from w, Gs, S
+- `void_ratio_from_dry_unit_weight(gamma_d, Gs)` -- compute e from gamma_d
+
+**Relative density**
+- `relative_density(e, e_max, e_min)` -- density index for granular soils
+
+**Atterberg limits and consistency**
+- `plasticity_index(LL, PL)` -- PI = LL - PL
+- `liquidity_index(w, PL, PI)` -- LI
+- `consistency_index(w, LL, PI)` -- CI
+
+### Core utilities
+
+- **Validation** -- input checking (positive, non-negative, range, fraction, angle)
+- **Constants** -- gravity, unit weight of water, atmospheric pressure
+- **Types** -- `Soil` dataclass for passing soil properties between functions
+
+---
+
+## Design principles
+
+- **Validated inputs.** Every function checks that values are physically
+  meaningful. Negative void ratios, impossible saturation, and bad angles
+  raise clear errors.
+- **Documented units.** Every docstring states what units are expected and
+  returned.
+- **Traceable methods.** Docstrings reference the source formula or textbook.
+- **No hidden dependencies.** v0.0.1 uses only the Python standard library.
+- **Tested.** Every formula is tested against hand-calculated values and
+  textbook examples.
+
+---
+
+## Roadmap
+
+| Version | Scope |
+|---------|-------|
+| v0.0.1  | Soil properties and phase relations |
+| v0.1.x  | Effective stress, pore pressure, seepage |
+| v0.2.x  | Shallow foundations, bearing capacity, settlement |
+| v0.3.x  | Soil classification (USCS), SPT/CPT correlations |
+| v0.4.x  | Earth pressure, consolidation, slope stability |
+| v0.5.x  | Pile capacity, liquefaction, advanced methods |
+| v1.0.0  | Stable API, full documentation, examples |
+
+---
+
+## Running the tests
+
+From a clone of this repository:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+If you only install pytest, tests still run from the project root (see `pythonpath` in `pyproject.toml`):
+
+```bash
+pip install pytest
+pytest
+```
+
+The wheel on PyPI does not include the test files; run tests from a source checkout.
+
+---
+
+## Contributing
+
+The repository is **private** until around **v0.5**; it will then be opened for
+public contributions. Until then, feedback and feature requests are appreciated.
+
+Every contribution should include the code, a test, a documentation update,
+and a reference for the method.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+Copyright (c) 2026 Ripon Chandra Malo

geoeq-0.0.1/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "geoeq"
+version = "0.0.1"
+description = "A Python library for geotechnical engineering calculations."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    {name = "Ripon Chandra Malo"},
+]
+keywords = [
+    "geoeq",
+    "geotechnical",
+    "soil mechanics",
+    "civil engineering",
+    "geotechnical engineering",
+    "soil properties",
+    "geotechnical interpretation",
+    "geotechnical formulas",
+    "bearing capacity",
+    "foundation",
+    "settlement",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "build",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/riponcm/geoeq"
+Repository = "https://github.com/riponcm/geoeq"
+Changelog = "https://github.com/riponcm/geoeq/blob/main/CHANGELOG.md"
+Issues = "https://github.com/riponcm/geoeq/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+geoeq = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

geoeq-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

geoeq-0.0.1/src/geoeq/__init__.py

@@ -0,0 +1,19 @@
+"""
+geoeq -- A Python library for geotechnical engineering calculations.
+
+Version 0.0.1 provides soil property and phase-relationship formulas.
+Future versions will add effective stress, bearing capacity, settlement,
+consolidation, earth pressure, slope stability, pile capacity,
+and liquefaction assessment.
+
+Quick start
+-----------
+>>> from geoeq.soil import properties as sp
+>>> sp.dry_unit_weight(Gs=2.65, e=0.72)
+15.11...
+"""
+
+__version__ = "0.0.1"
+
+from . import core
+from . import soil

geoeq-0.0.1/src/geoeq/core/__init__.py

@@ -0,0 +1,13 @@
+"""
+geoeq.core -- constants, validation, and types.
+"""
+
+from .constants import GRAVITY, GAMMA_WATER, DENSITY_WATER, ATMOSPHERIC_PRESSURE
+from .validation import (
+    check_positive,
+    check_non_negative,
+    check_range,
+    check_fraction,
+    check_angle_degrees,
+)
+from .types import Soil

geoeq-0.0.1/src/geoeq/core/constants.py

@@ -0,0 +1,22 @@
+"""
+Physical and engineering constants used across geoeq.
+
+All values are in SI units unless stated otherwise.
+"""
+
+import math
+
+# Acceleration due to gravity (m/s^2).
+GRAVITY = 9.81
+
+# Unit weight of water (kN/m^3).
+GAMMA_WATER = 9.81
+
+# Density of water (kg/m^3).
+DENSITY_WATER = 1000.0
+
+# Atmospheric pressure (kPa).
+ATMOSPHERIC_PRESSURE = 101.325
+
+# Pi.
+PI = math.pi

geoeq-0.0.1/src/geoeq/core/types.py

@@ -0,0 +1,47 @@
+"""
+Common data structures for geoeq.
+
+Using dataclasses keeps data structured and inspectable rather than
+passing around bare dictionaries.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Soil:
+    """
+    Represents a soil with basic engineering properties.
+
+    Parameters
+    ----------
+    gamma : float
+        Total unit weight (kN/m^3).  Default 18.0.
+    phi : float
+        Effective friction angle (degrees).  Default 30.0.
+    c : float
+        Effective cohesion (kPa).  Default 0.0.
+    e : float or None
+        Void ratio.  Default ``None``.
+    Gs : float
+        Specific gravity of solids.  Default 2.65.
+    w : float or None
+        Water content as a decimal (e.g. 0.25 for 25 %).  Default ``None``.
+    gamma_d : float or None
+        Dry unit weight (kN/m^3).  Default ``None``.
+    Su : float or None
+        Undrained shear strength (kPa).  Default ``None``.
+    description : str
+        Free-text label.  Default ``""``.
+    """
+
+    gamma: float = 18.0
+    phi: float = 30.0
+    c: float = 0.0
+    e: Optional[float] = None
+    Gs: float = 2.65
+    w: Optional[float] = None
+    gamma_d: Optional[float] = None
+    Su: Optional[float] = None
+    description: str = ""

geoeq-0.0.1/src/geoeq/core/validation.py

@@ -0,0 +1,50 @@
+"""
+Input validation utilities for geoeq.
+
+Every public function should validate its inputs before computing.
+These helpers raise ``ValueError`` with clear messages when inputs
+fall outside physically meaningful ranges.
+"""
+
+
+def check_positive(value: float, name: str) -> None:
+    """Raise ``ValueError`` if *value* is not strictly positive."""
+    if value <= 0:
+        raise ValueError(f"{name} must be positive, got {value}")
+
+
+def check_non_negative(value: float, name: str) -> None:
+    """Raise ``ValueError`` if *value* is negative."""
+    if value < 0:
+        raise ValueError(f"{name} must be non-negative, got {value}")
+
+
+def check_range(
+    value: float,
+    name: str,
+    low: float,
+    high: float,
+    inclusive: bool = True,
+) -> None:
+    """Raise ``ValueError`` if *value* is outside [low, high] (or (low, high))."""
+    if inclusive:
+        if value < low or value > high:
+            raise ValueError(f"{name} must be in [{low}, {high}], got {value}")
+    else:
+        if value <= low or value >= high:
+            raise ValueError(f"{name} must be in ({low}, {high}), got {value}")
+
+
+def check_fraction(value: float, name: str) -> None:
+    """Raise ``ValueError`` if *value* is not in [0, 1]."""
+    check_range(value, name, 0.0, 1.0)
+
+
+def check_angle_degrees(
+    value: float,
+    name: str,
+    low: float = 0.0,
+    high: float = 90.0,
+) -> None:
+    """Raise ``ValueError`` if an angle in degrees is outside [low, high]."""
+    check_range(value, name, low, high)

geoeq-0.0.1/src/geoeq/soil/__init__.py

@@ -0,0 +1,6 @@
+"""
+geoeq.soil -- soil property formulas.
+"""
+
+from . import properties
+from geoeq.core.types import Soil