lythossettle 0.1.0__py3-none-any.whl

lythossettle/__init__.py

@@ -0,0 +1,45 @@
+"""
+Lythos Settle — settlement analysis of shallow foundations, driven from a browser.
+
+The program works out how much, and how fast, a shallow foundation settles on
+a layered soil profile:
+
+    1. Stresses        — in-situ σ'v0 and σ'p; the stress increase beneath the
+                         foundation by Boussinesq (rectangle, strip, circle) or 2:1
+    2. Immediate       — layered elastic (Steinbrenner) or Schmertmann (1978)
+    3. Consolidation   — primary settlement of the clay layers from Cc, Cr, e0
+                         and σ'p, and secondary compression from Cα
+    4. Time            — Terzaghi's one-dimensional consolidation, per layer
+    5. Checks          — total settlement and angular distortion
+
+On top of it, a parametric or reliability study sweeps any input (a range, or
+a distribution) and reports sensitivities and the probability of exceeding
+the allowable settlement.
+
+The interface is a local web server driven from the browser (standard library
+only), so the program also runs over a remote session or inside a container,
+where a desktop toolkit would need a display it does not have.
+
+Package layout
+--------------
+    lythossettle.config         app identity, defaults, themes, palette
+    lythossettle.i18n           every text of the program, English and Turkish
+    lythossettle.stress         Boussinesq, 2:1 and Steinbrenner solutions
+    lythossettle.consolidation  Terzaghi time factor, compression of clay
+    lythossettle.engine         the settlement analysis
+    lythossettle.study          parametric / reliability studies
+    lythossettle.plotting       analysis figures
+    lythossettle.study_plots    study figures
+    lythossettle.report         calculation report: HTML, PDF, DOCX
+    lythossettle.forms          input schema and readers (interface-independent)
+    lythossettle.web            local web server and the browser interface
+
+Run it:  lythos-settle            (or  python -m lythossettle)
+"""
+
+__version__ = "0.1.0"
+
+APP_NAME = "Lythos Settle"
+ORG = "Lythos"
+
+__all__ = ["__version__", "APP_NAME", "ORG"]

lythossettle/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m lythossettle` opens the interface in a browser."""
+import sys
+
+from .cli import main
+
+sys.exit(main())

lythossettle/cli.py

@@ -0,0 +1,137 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import APP_NAME, __version__
+
+#: Default port of the local interface (the family counts up from 8777)
+PORT = 8780
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="lythos-settle",
+        description="Settlement analysis of shallow foundations: stress distribution, "
+                    "immediate (elastic / Schmertmann), consolidation and secondary "
+                    "settlement, consolidation time, and parametric / reliability studies.")
+    parser.add_argument("--version", action="version", version=f"{APP_NAME} {__version__}")
+    # Running the program with no subcommand means "web", so the top level
+    # carries that subcommand's defaults: without them the bare `lythos-settle`
+    # would reach serve() with a Namespace that has no host, port or language.
+    parser.set_defaults(host="127.0.0.1", port=PORT, lang="en", no_browser=False)
+    sub = parser.add_subparsers(dest="command")
+
+    web = sub.add_parser("web", help="start the interface in a browser")
+    web.add_argument("--port", type=int, default=PORT)
+    web.add_argument("--host", default="127.0.0.1")
+    web.add_argument("--lang", default="en", choices=["en", "tr"])
+    web.add_argument("--no-browser", action="store_true")
+
+    run = sub.add_parser("run", help="analyse a project file and print the results")
+    run.add_argument("project", help="path to a .settle / .json project file")
+    run.add_argument("-o", "--out", default=None,
+                     help="write a report here (.pdf / .html / .docx)")
+    run.add_argument("--lang", default="en", choices=["en", "tr"])
+
+    study = sub.add_parser("study", help="run the study defined in a project file")
+    study.add_argument("project", help="path to a .settle / .json project file")
+    study.add_argument("-o", "--out", default=None, help="write the samples here (.csv / .xlsx)")
+    study.add_argument("--lang", default="en", choices=["en", "tr"])
+
+    example = sub.add_parser("example", help="write a starter project file")
+    example.add_argument("-o", "--out", default="project.settle")
+
+    args = parser.parse_args(argv)
+    command = args.command or "web"
+    try:
+        return _dispatch(command, args)
+    except (ValueError, RuntimeError, OSError) as exc:
+        # The analysis refuses impossible input with a sentence worth reading
+        # (a foundation below the profile, a layer without a modulus, an
+        # unreadable project file). A traceback would bury it, so only
+        # unexpected failures keep theirs.
+        print(f"{APP_NAME}: {exc}", file=sys.stderr)
+        return 1
+
+
+def _example_study(values: dict) -> list:
+    """Two study variables for the starter project, so `study` has something to do."""
+    return [
+        {"path": "foundation.q", "label": "Foundation · q", "mode": "dist", "dist": "normal",
+         "mean": values["q"], "cov": 0.10, "min": 0, "max": 0, "n_points": 5},
+        {"path": "soil_profile.2.Cc", "label": "Soft clay · Cc", "mode": "dist",
+         "dist": "lognormal", "mean": values["soil_profile"][2]["Cc"], "cov": 0.25,
+         "min": 0, "max": 0, "n_points": 5},
+    ]
+
+
+def _dispatch(command: str, args) -> int:
+    """Runs one command; raises on anything that goes wrong."""
+    if command == "web":
+        from .web.server import serve
+        serve(host=args.host, port=args.port, open_browser=not args.no_browser,
+              lang=args.lang)
+        return 0
+
+    from . import forms
+
+    if command == "example":
+        values = forms.defaults()
+        values["study_variables"] = _example_study(values)
+        with open(args.out, "w", encoding="utf-8") as fh:
+            json.dump(forms.project_file(values), fh, indent=2, ensure_ascii=False)
+        print(args.out)
+        return 0
+
+    with open(args.project, encoding="utf-8") as fh:
+        data = json.load(fh)
+
+    from .web.session import Session
+    session = Session(lang=args.lang)
+    values = session.load_project(data)["values"]
+
+    if command == "run":
+        result = session.analyse(values)
+        print(result["text"])
+        if args.out:
+            fmt = args.out.lower().rsplit(".", 1)[-1]
+            print(session.report(fmt if fmt in ("pdf", "html", "docx") else "pdf", args.out))
+        return 0
+
+    # A study: analyse the foundation first, so the report and the figures
+    # have something to sit beside, then sample.
+    session.analyse(values)
+    started = session.start_study(values)
+    if not started["ok"]:
+        print(started["error"], file=sys.stderr)
+        return 1
+    import time
+    last = -1
+    while session.state()["job"] == "running":
+        state = session.state()
+        if state["total"] and state["done"] != last:
+            last = state["done"]
+            print(f"\r{state['done']} / {state['total']}", end="", file=sys.stderr, flush=True)
+        time.sleep(0.2)
+    print("", file=sys.stderr)
+    state = session.state()
+    if state["job"] == "error":
+        print(state["error"], file=sys.stderr)
+        return 1
+    payload = session.study_payload()
+    if not payload["ok"]:
+        print(payload["error"], file=sys.stderr)
+        return 1
+    print(payload["text"])
+    if args.out:
+        kind = "xlsx" if args.out.lower().endswith(".xlsx") else "csv"
+        print(session.export_study(kind, args.out))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lythossettle/config.py

@@ -0,0 +1,116 @@
+"""
+Configuration for Lythos Settle: the default project, the choice lists, and
+the theme and plot palette shared by the page and the figures.
+
+The app name and version live in the package's ``__init__`` so that there is
+one copy of each; the translations live in `lythossettle.i18n`.
+"""
+
+from . import APP_NAME
+from . import __version__ as APP_VERSION
+
+__all__ = ["APP_NAME", "APP_VERSION", "DEFAULT_CONFIG", "THEMES", "PLOT_PALETTE",
+           "SOIL_FILL", "SHAPES", "STRESS_METHODS", "IMMEDIATE_METHODS", "RIGIDITY",
+           "BEHAVIOURS", "DRAINAGE", "ACCENT"]
+
+MM_PER_M = 1000.0
+
+# --- Choice lists (the first entry is the default where one is needed) -----
+SHAPES = ["rectangle", "strip", "circle", "embankment"]
+STRESS_METHODS = ["boussinesq", "two_to_one"]
+IMMEDIATE_METHODS = ["elastic", "schmertmann"]
+RIGIDITY = ["flexible", "rigid"]
+BEHAVIOURS = ["granular", "cohesive"]
+DRAINAGE = ["double", "single"]
+
+# --- Interface theme (web/static/style.css) and plot palette ---------------
+# --- kept together so the figures always match the page they are shown on. -
+ACCENT = "#C6613F"
+
+THEMES = {
+    "dark": dict(bg="#262624", panel="#30302E", input_bg="#262624", fg="#F5F4ED",
+                 fg_dim="#A6A39A", border="#4A4944", hover="#3A3A37", btn="#3A3A37",
+                 muted="#6B6A64", accent="#D97757", accent_hover="#E08B6E"),
+    "light": dict(bg="#F5F4ED", panel="#FAF9F5", input_bg="#FFFFFF", fg="#141413",
+                  fg_dim="#73726C", border="#E3E0D5", hover="#F0EEE6", btn="#F0EEE6",
+                  muted="#B7B4AA", accent=ACCENT, accent_hover="#B0532F"),
+}
+# The report's figures: the light palette on white paper.
+THEMES["paper"] = dict(THEMES["light"], bg="#FFFFFF", panel="#FFFFFF")
+
+# Semantic colours: the same quantity is the same colour in every figure. Warm and
+# muted, to sit on the paper-coloured page; terracotta marks the total.
+PLOT_PALETTE = dict(
+    immediate="#5B8DB8", consolidation="#8C6BB1", secondary="#D9A55B",
+    total="#C6613F", stress="#4E9A8A", overburden="#73726C", preconsolidation="#5E8C4A",
+    limit="#A26A12", water="#6FA8C7", footing="#8A8680",
+    center="#C6613F", char="#8C6BB1", edge="#D9A55B", corner="#4E9A8A",
+    shoulder="#8C6BB1", midslope="#D9A55B", toe="#4E9A8A", fill="#C9A876",
+    allowable="#B0413E",
+)
+
+# Fill colours of the two soil behaviours in the schematic (theme-dependent,
+# since a light sandy tone reads poorly on a dark background).
+SOIL_FILL = {
+    "light": {"granular": "#E3C98F", "cohesive": "#A7B8A0"},
+    "dark": {"granular": "#8A7250", "cohesive": "#5E6E58"},
+}
+SOIL_FILL["paper"] = SOIL_FILL["light"]
+
+DEFAULT_CONFIG = {
+    "project_info": {
+        "title": "Project: Raft on soft clay",
+        "analyst": "",
+    },
+    "foundation": {
+        "shape": "rectangle",
+        "B": 8.0,                  # width, or diameter of a circle [m]
+        "L": 16.0,                 # length of a rectangle [m]
+        "Df": 1.5,                 # depth of the foundation base [m]
+        "q": 100.0,                # applied (gross) bearing pressure [kPa]
+        "net_pressure": True,      # deduct the overburden removed by the excavation
+    },
+    # An embankment (shape "embankment"): a long trapezoidal fill on the ground
+    # surface, loading it with γ·H under the crest and less under the slopes.
+    "embankment": {
+        "crest": 12.0,             # crest width [m]
+        "height": 4.0,             # [m]
+        "slope_left": 26.57,       # slope angles from the horizontal [°] (1V:2H)
+        "slope_right": 26.57,
+        "gamma": 20.0,             # unit weight of the fill [kN/m³]
+    },
+    "groundwater": {
+        "depth": 2.0,              # below ground surface [m]
+        "gamma_water": 9.81,       # [kN/m³]
+    },
+    # Layers from the ground surface down. E [MPa] is the drained modulus of
+    # a granular layer and the undrained modulus of a cohesive one; cv in
+    # m²/year; OCR = σ'p / σ'v0.
+    "soil_profile": [
+        {"name": "Fill", "thickness": 1.5, "behaviour": "granular", "gamma": 18.0,
+         "gamma_sat": 19.0, "E": 10.0, "nu": 0.30, "Cc": 0.0, "Cr": 0.0, "e0": 0.6,
+         "OCR": 1.0, "cv": 0.0, "Calpha": 0.0, "drainage": "double"},
+        {"name": "Medium dense sand", "thickness": 3.5, "behaviour": "granular",
+         "gamma": 18.5, "gamma_sat": 20.0, "E": 25.0, "nu": 0.30, "Cc": 0.0, "Cr": 0.0,
+         "e0": 0.6, "OCR": 1.0, "cv": 0.0, "Calpha": 0.0, "drainage": "double"},
+        {"name": "Soft clay", "thickness": 6.0, "behaviour": "cohesive", "gamma": 17.0,
+         "gamma_sat": 17.5, "E": 6.0, "nu": 0.50, "Cc": 0.32, "Cr": 0.05, "e0": 1.05,
+         "OCR": 1.3, "cv": 1.5, "Calpha": 0.010, "drainage": "double"},
+        {"name": "Dense sand", "thickness": 10.0, "behaviour": "granular", "gamma": 19.5,
+         "gamma_sat": 21.0, "E": 60.0, "nu": 0.30, "Cc": 0.0, "Cr": 0.0, "e0": 0.5,
+         "OCR": 1.0, "cv": 0.0, "Calpha": 0.0, "drainage": "double"},
+    ],
+    "options": {
+        "stress_method": "boussinesq",
+        "immediate_method": "elastic",
+        "rigidity": "flexible",
+        "sublayer": 0.25,          # thickness of the calculation sublayers [m]
+        "depth_ratio": 0.10,       # influence depth where Δσ = ratio · σ'v0 (0: whole profile)
+        "design_life": 50.0,       # years, for secondary compression and creep
+        "creep": True,             # Schmertmann's time factor C2
+    },
+    "criteria": {
+        "s_allow": 150.0,          # allowable total settlement [mm] (0: no check)
+        "distortion_allow": 500.0,  # allowable angular distortion 1 / x (0: no check)
+    },
+}

lythossettle/consolidation.py

@@ -0,0 +1,100 @@
+"""
+One-dimensional consolidation: Terzaghi's theory, and the settlement of a
+clay sublayer from its compression indices.
+
+Time
+    U(Tv) is the average degree of consolidation for a uniform initial excess
+    pore pressure: the Fourier series, with Terzaghi's √(4Tv/π) where the
+    series would need too many terms. Tv(U) is its inverse, found by
+    bisection so that U(Tv(U)) = U to the precision of the series, rather
+    than by the usual two-branch approximation.
+
+Magnitude
+    Δe from Cc and Cr about the preconsolidation pressure σ'p: the
+    recompression line up to σ'p and the virgin line beyond it.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+#: Terms of the Fourier series (plenty for Tv ≥ 1e-3)
+TERMS = 200
+
+#: Below this Tv the series is replaced by √(4Tv/π) (identical there to 1e-9)
+TV_SMALL = 1e-3
+
+#: Degree of consolidation taken as the end of primary consolidation, from
+#: which secondary compression is counted
+U_END_OF_PRIMARY = 0.95
+
+
+def degree(Tv) -> np.ndarray:
+    """Average degree of consolidation U for time factor(s) Tv."""
+    Tv = np.atleast_1d(np.asarray(Tv, dtype=float))
+    Tv = np.maximum(Tv, 0.0)
+    m = np.arange(TERMS)
+    M = np.pi * (2 * m + 1) / 2.0
+    series = 1.0 - np.sum(2.0 / M ** 2 * np.exp(-np.outer(np.maximum(Tv, TV_SMALL), M ** 2)),
+                          axis=1)
+    small = np.sqrt(4.0 * Tv / np.pi)
+    return np.clip(np.where(Tv < TV_SMALL, small, series), 0.0, 1.0)
+
+
+def time_factor(U: float) -> float:
+    """Time factor Tv at which the average degree of consolidation is U."""
+    if not 0.0 < U < 1.0:
+        raise ValueError("the degree of consolidation must be between 0 and 1")
+    lo, hi = 0.0, 10.0
+    for _ in range(80):
+        mid = 0.5 * (lo + hi)
+        if degree(mid)[0] < U:
+            lo = mid
+        else:
+            hi = mid
+    return 0.5 * (lo + hi)
+
+
+def drainage_path(thickness: float, drainage: str) -> float:
+    """Longest drainage path: half the layer when both faces drain."""
+    return thickness / 2.0 if drainage == "double" else thickness
+
+
+def time_for(U: float, cv: float, h_dr: float) -> float:
+    """Time (in the units of cv) to reach degree of consolidation U."""
+    if cv <= 0:
+        return float("nan")
+    return time_factor(U) * h_dr * h_dr / cv
+
+
+def degree_at(t, cv: float, h_dr: float) -> np.ndarray:
+    """U at time(s) t for a layer with coefficient cv and drainage path h_dr.
+
+    A layer without cv is taken as consolidating at once (U = 1)."""
+    t = np.atleast_1d(np.asarray(t, dtype=float))
+    if cv <= 0 or h_dr <= 0:
+        return np.ones_like(t)
+    return degree(cv * t / (h_dr * h_dr))
+
+
+def primary_strain(sigma0, dsigma, sigma_p, Cc: float, Cr: float, e0: float) -> np.ndarray:
+    """Vertical strain Δe / (1 + e0) of clay loaded from σ'0 by Δσ.
+
+    σ'0 ≥ σ'p is normally consolidated; below it the recompression line is
+    followed up to σ'p (or the final stress, whichever is lower) and the
+    virgin line beyond.
+    """
+    s0 = np.maximum(np.atleast_1d(np.asarray(sigma0, dtype=float)), 1e-6)
+    sf = np.maximum(s0 + np.maximum(np.asarray(dsigma, dtype=float), 0.0), s0)
+    sp = np.maximum(np.asarray(sigma_p, dtype=float), s0)
+    recompression = Cr * np.log10(np.minimum(sf, sp) / s0)
+    virgin = Cc * np.log10(np.maximum(sf, sp) / sp)
+    return (recompression + virgin) / (1.0 + e0)
+
+
+def secondary_strain(t, t_p: float, Calpha: float, e0: float) -> np.ndarray:
+    """Secondary compression strain Cα/(1 + e0)·log10(t / t_p), zero before t_p."""
+    t = np.atleast_1d(np.asarray(t, dtype=float))
+    if Calpha <= 0 or not np.isfinite(t_p) or t_p <= 0:
+        return np.zeros_like(t)
+    return Calpha / (1.0 + e0) * np.log10(np.maximum(t / t_p, 1.0))