lythossettle 0.1.0__tar.gz

lythossettle-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hasan Deniz Altuntaş
+
+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.

lythossettle-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: lythossettle
+Version: 0.1.0
+Summary: Settlement analysis of shallow foundations and embankments: Boussinesq / 2:1 stress distribution, immediate settlement (Steinbrenner, Schmertmann), primary consolidation and secondary compression, Terzaghi time–settlement, and parametric / reliability studies with PDF reporting.
+Author-email: Hasan Deniz Altuntaş <lythosfea@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hdaltuntas/lythos-settle
+Project-URL: Repository, https://github.com/hdaltuntas/lythos-settle
+Project-URL: Issues, https://github.com/hdaltuntas/lythos-settle/issues
+Project-URL: Releasing, https://github.com/hdaltuntas/lythos-settle/blob/main/docs/releasing.md
+Keywords: geotechnical,settlement,foundation,shallow foundation,raft,footing,consolidation,terzaghi,boussinesq,steinbrenner,schmertmann,secondary compression,angular distortion,reliability,monte carlo,civil engineering
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Turkish
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: reportlab>=4.0
+Provides-Extra: docx
+Requires-Dist: python-docx>=0.8; extra == "docx"
+Provides-Extra: xlsx
+Requires-Dist: openpyxl>=3.0; extra == "xlsx"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: python-docx>=0.8; extra == "dev"
+Requires-Dist: openpyxl>=3.0; extra == "dev"
+Dynamic: license-file
+
+**English** | [Türkçe](https://github.com/hdaltuntas/lythos-settle/blob/main/README.tr.md)
+
+# Lythos Settle
+
+[![Tests](https://github.com/hdaltuntas/lythos-settle/actions/workflows/tests.yml/badge.svg)](https://github.com/hdaltuntas/lythos-settle/actions/workflows/tests.yml)
+
+Settlement analysis of shallow foundations and embankments, driven from your browser. A
+rectangular, strip or circular foundation — or an embankment given by its crest width,
+height and slope angles — on a layered soil profile is analysed for **how much** it settles
+and **how fast**:
+
+1. **Stresses** — in-situ σv0, u0, σ'v0 and σ'p; the stress increase beneath the foundation
+   by Boussinesq (Newmark's rectangle, the strip and the circle solutions) or by the 2:1
+   spread, at the centre, the characteristic point, the middle of the long edge and the corner;
+   under an embankment, exactly for its trapezoidal load, at the crest centre, the crest edge,
+   the middle of the slope and the toe.
+2. **Immediate settlement** — layered elastic (Steinbrenner) in every layer, or
+   Schmertmann (1978) in the granular layers.
+3. **Consolidation** — primary settlement of the clay layers from Cc, Cr, e0 and σ'p, and
+   secondary compression from Cα up to the design life.
+4. **Time** — Terzaghi's one-dimensional consolidation, each clay layer draining on its own;
+   t50, t90 and the time–settlement curve.
+5. **Checks** — total settlement and angular distortion against their allowable values.
+
+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 or distortion, with a confidence interval and the reliability index β.
+
+The whole program — every label, result text, figure and report — is bilingual in
+**English and Turkish**, switchable while it runs.
+
+The interface is a small HTTP server on your own machine, driven from a browser. That
+keeps the program usable over a remote session or inside a container, where a desktop
+toolkit would need a display it does not have, and it costs no dependency beyond the
+standard library.
+
+> This is the sibling of [LythosFEA](https://github.com/hdaltuntas/lythos),
+> [Lythos Kinematic](https://github.com/hdaltuntas/lythoskinematic),
+> [Lythos SPWA](https://github.com/hdaltuntas/lythosspwa) and
+> [LythosLE](https://github.com/hdaltuntas/lythosle), and follows the same architecture.
+
+## Screenshots
+
+| Results summary | Time–settlement |
+|---|---|
+| ![Results summary](https://raw.githubusercontent.com/hdaltuntas/lythos-settle/main/screenshots/settle_summary.png) | ![Time–settlement](https://raw.githubusercontent.com/hdaltuntas/lythos-settle/main/screenshots/settle_time.png) |
+
+| Reliability study | Settlement with depth, dark theme, Turkish |
+|---|---|
+| ![Study](https://raw.githubusercontent.com/hdaltuntas/lythos-settle/main/screenshots/settle_study.png) | ![Settlement with depth](https://raw.githubusercontent.com/hdaltuntas/lythos-settle/main/screenshots/settle_depth_dark_tr.png) |
+
+| Embankment on soft clay | Settlement across the embankment |
+|---|---|
+| ![Embankment](https://raw.githubusercontent.com/hdaltuntas/lythos-settle/main/screenshots/settle_embankment.png) | ![Settlement across the embankment](https://raw.githubusercontent.com/hdaltuntas/lythos-settle/main/screenshots/settle_embankment_profile.png) |
+
+## Install & run
+
+From a clone, with nothing installed but the scientific stack:
+
+```bash
+pip install numpy matplotlib reportlab
+python main.py
+```
+
+or install it and use the command:
+
+```bash
+pip install .
+lythos-settle                      # opens the interface in your browser
+```
+
+`main.py` puts its own directory first on the import path, so the clone's code is what
+runs even when `lythossettle` is also installed.
+
+Python 3.10+ is required. Word reports need `python-docx` and the spreadsheet export of a
+study needs `openpyxl`; both are extras (`pip install ".[docx,xlsx]"`).
+
+## Command line
+
+```bash
+lythos-settle                                  # web interface (the default)
+lythos-settle web --port 9000 --lang tr --no-browser
+lythos-settle example -o project.settle        # a starter project file
+lythos-settle run project.settle -o report.pdf # analyse, print the results, write a report
+lythos-settle study project.settle -o samples.csv
+```
+
+`run` and `study` read the same `.settle` file the interface saves, so a case set up in
+the browser can be re-run unattended.
+
+## Inputs
+
+* **Foundation:** shape (rectangle, strip, circle), B (diameter of a circle), L, depth Df,
+  gross bearing pressure q; optionally the excavated overburden is deducted
+  (q_net = q − σv0(Df)).
+* **Embankment** (shape "embankment"): crest width, height H, left and right slope angles
+  from the horizontal, unit weight of the fill γ; the load is γ·H under the crest, falling
+  linearly to zero at the toes.
+* **Groundwater:** depth of the water table, γw.
+* **Soil profile**, from the surface down, one row per layer: thickness, granular or
+  cohesive, γ, γsat, E, ν, and for the clays Cc, Cr, e0, OCR, cv, Cα and single / double
+  drainage. E is the drained modulus of a sand and the undrained modulus of a clay.
+* **Options:** stress distribution, immediate-settlement method, flexible or rigid
+  foundation, sublayer thickness, influence-depth ratio Δσ/σ'v0, design life, Schmertmann's
+  creep factor.
+* **Criteria:** allowable total settlement and angular distortion (1/x).
+
+## What it computes
+
+| quantity | method |
+|---|---|
+| Δσ under a rectangle | Newmark's integration of Boussinesq, superposed for any point |
+| Δσ under a strip / circle | closed form / exact one-dimensional integral over the polar angle |
+| Δσ under an embankment | exact: Flamant's line load integrated over the piecewise-linear (trapezoidal) load |
+| Δσ, approximate | 2:1 spread |
+| embankment, immediate | Steinbrenner in plane strain, the crest as one strip and each slope as 16 slices |
+| immediate settlement | Steinbrenner F1, F2 on each layer (layered elastic), or Schmertmann (1978) with C1, C2 and the L/B-interpolated influence diagram |
+| primary consolidation | Cr up to σ'p = OCR·σ'v0, Cc beyond it, sublayer by sublayer at each point |
+| secondary compression | Cα/(1+e0)·H·log(t/t_p) from U = 95 % to the design life; Cα·Cr/Cc where the clay stays over-consolidated |
+| time | Terzaghi U(Tv), per clay layer, H_dr = H/2 or H |
+| rigid foundation | settlement of the characteristic point (0.74·B/2, 0.74·L/2; 0.845·R) |
+| angular distortion | (s_centre − s_edge) / (B/2) |
+
+The derivations and their limits are in [docs/theory.md](https://github.com/hdaltuntas/lythos-settle/blob/main/docs/theory.md).
+
+## Figures
+
+Section with the Boussinesq stress bulb · stresses with depth (σ'v0, σ'v0 + Δσ, σ'p and the
+influence-depth criterion) · influence factors at each point with Schmertmann's Iz ·
+cumulative settlement with depth · time–settlement curve · settlement components at each
+point · settlement across the section (the settlement trough under a footing or a fill). Study figures: one-at-a-time sweep, histogram, scatter, tornado.
+
+## Reports
+
+Choose PDF, self-contained HTML or Word in the header and press *Export report…*. The
+report carries the inputs, the stresses, the settlement at each point and in each layer,
+the Schmertmann factors, the consolidation times, the checks, the figures, the warnings,
+the method notes and — if one was run — the study, in whichever language the interface is
+in. All three formats are assembled from one place, so they say the same thing.
+
+## Project files (`.settle`)
+
+JSON. *Save* writes the inputs and the study definition; *Open…* reads them back. Missing
+entries keep their defaults.
+
+## Modules
+
+| file | content |
+|---|---|
+| `lythossettle/stress.py` | Boussinesq (rectangle, strip, circle), 2:1, Steinbrenner |
+| `lythossettle/consolidation.py` | Terzaghi U(Tv) and its inverse, compression of clay, secondary compression |
+| `lythossettle/engine.py` | The settlement analysis: profile, sublayers, points, checks, time curve |
+| `lythossettle/study.py`, `study_plots.py` | Parametric (one at a time) and reliability (LHS / Monte Carlo) studies, statistics, P of exceedance with 95 % CI and β, Spearman sensitivities, CSV / XLSX |
+| `lythossettle/plotting.py`, `plot_style.py`, `render.py` | Matplotlib figures, theme-aware, off-screen |
+| `lythossettle/report.py`, `pdf.py` | Calculation report: one HTML assembly, exported as PDF (reportlab), HTML or DOCX |
+| `lythossettle/forms.py` | Input schema and readers; converts between the interface's flat values and the engine's configuration |
+| `lythossettle/summary.py` | The results as cards and as text, for the browser and the command line alike |
+| `lythossettle/i18n.py` | Every text, English and Turkish, written side by side |
+| `lythossettle/web/` | The local HTTP server, the session, and the browser interface |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q                 # engine against hand calculations, stresses against tables, study, report, web, packaging
+ruff check .
+```
+
+The tests check the stress solutions against published values and brute-force integrals,
+the engine against closed-form cases (a square on an elastic half-space, a one-dimensional
+clay layer, Schmertmann by hand), the report in all three formats, the input schema and its
+file round-trips, and the interface itself — the session and the HTTP layer both, so the
+browser is exercised without a browser.
+
+Releasing to PyPI is described in [docs/releasing.md](https://github.com/hdaltuntas/lythos-settle/blob/main/docs/releasing.md);
+`tools/upload_to_pypi.py` does it from an editor, without a terminal.
+
+## License
+
+[MIT](https://github.com/hdaltuntas/lythos-settle/blob/main/LICENSE) © 2026 Hasan Deniz Altuntaş

lythossettle-0.1.0/README.md

@@ -0,0 +1,180 @@
+**English** | [Türkçe](https://github.com/hdaltuntas/lythos-settle/blob/main/README.tr.md)
+
+# Lythos Settle
+
+[![Tests](https://github.com/hdaltuntas/lythos-settle/actions/workflows/tests.yml/badge.svg)](https://github.com/hdaltuntas/lythos-settle/actions/workflows/tests.yml)
+
+Settlement analysis of shallow foundations and embankments, driven from your browser. A
+rectangular, strip or circular foundation — or an embankment given by its crest width,
+height and slope angles — on a layered soil profile is analysed for **how much** it settles
+and **how fast**:
+
+1. **Stresses** — in-situ σv0, u0, σ'v0 and σ'p; the stress increase beneath the foundation
+   by Boussinesq (Newmark's rectangle, the strip and the circle solutions) or by the 2:1
+   spread, at the centre, the characteristic point, the middle of the long edge and the corner;
+   under an embankment, exactly for its trapezoidal load, at the crest centre, the crest edge,
+   the middle of the slope and the toe.
+2. **Immediate settlement** — layered elastic (Steinbrenner) in every layer, or
+   Schmertmann (1978) in the granular layers.
+3. **Consolidation** — primary settlement of the clay layers from Cc, Cr, e0 and σ'p, and
+   secondary compression from Cα up to the design life.
+4. **Time** — Terzaghi's one-dimensional consolidation, each clay layer draining on its own;
+   t50, t90 and the time–settlement curve.
+5. **Checks** — total settlement and angular distortion against their allowable values.
+
+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 or distortion, with a confidence interval and the reliability index β.
+
+The whole program — every label, result text, figure and report — is bilingual in
+**English and Turkish**, switchable while it runs.
+
+The interface is a small HTTP server on your own machine, driven from a browser. That
+keeps the program usable over a remote session or inside a container, where a desktop
+toolkit would need a display it does not have, and it costs no dependency beyond the
+standard library.
+
+> This is the sibling of [LythosFEA](https://github.com/hdaltuntas/lythos),
+> [Lythos Kinematic](https://github.com/hdaltuntas/lythoskinematic),
+> [Lythos SPWA](https://github.com/hdaltuntas/lythosspwa) and
+> [LythosLE](https://github.com/hdaltuntas/lythosle), and follows the same architecture.
+
+## Screenshots
+
+| Results summary | Time–settlement |
+|---|---|
+| ![Results summary](https://raw.githubusercontent.com/hdaltuntas/lythos-settle/main/screenshots/settle_summary.png) | ![Time–settlement](https://raw.githubusercontent.com/hdaltuntas/lythos-settle/main/screenshots/settle_time.png) |
+
+| Reliability study | Settlement with depth, dark theme, Turkish |
+|---|---|
+| ![Study](https://raw.githubusercontent.com/hdaltuntas/lythos-settle/main/screenshots/settle_study.png) | ![Settlement with depth](https://raw.githubusercontent.com/hdaltuntas/lythos-settle/main/screenshots/settle_depth_dark_tr.png) |
+
+| Embankment on soft clay | Settlement across the embankment |
+|---|---|
+| ![Embankment](https://raw.githubusercontent.com/hdaltuntas/lythos-settle/main/screenshots/settle_embankment.png) | ![Settlement across the embankment](https://raw.githubusercontent.com/hdaltuntas/lythos-settle/main/screenshots/settle_embankment_profile.png) |
+
+## Install & run
+
+From a clone, with nothing installed but the scientific stack:
+
+```bash
+pip install numpy matplotlib reportlab
+python main.py
+```
+
+or install it and use the command:
+
+```bash
+pip install .
+lythos-settle                      # opens the interface in your browser
+```
+
+`main.py` puts its own directory first on the import path, so the clone's code is what
+runs even when `lythossettle` is also installed.
+
+Python 3.10+ is required. Word reports need `python-docx` and the spreadsheet export of a
+study needs `openpyxl`; both are extras (`pip install ".[docx,xlsx]"`).
+
+## Command line
+
+```bash
+lythos-settle                                  # web interface (the default)
+lythos-settle web --port 9000 --lang tr --no-browser
+lythos-settle example -o project.settle        # a starter project file
+lythos-settle run project.settle -o report.pdf # analyse, print the results, write a report
+lythos-settle study project.settle -o samples.csv
+```
+
+`run` and `study` read the same `.settle` file the interface saves, so a case set up in
+the browser can be re-run unattended.
+
+## Inputs
+
+* **Foundation:** shape (rectangle, strip, circle), B (diameter of a circle), L, depth Df,
+  gross bearing pressure q; optionally the excavated overburden is deducted
+  (q_net = q − σv0(Df)).
+* **Embankment** (shape "embankment"): crest width, height H, left and right slope angles
+  from the horizontal, unit weight of the fill γ; the load is γ·H under the crest, falling
+  linearly to zero at the toes.
+* **Groundwater:** depth of the water table, γw.
+* **Soil profile**, from the surface down, one row per layer: thickness, granular or
+  cohesive, γ, γsat, E, ν, and for the clays Cc, Cr, e0, OCR, cv, Cα and single / double
+  drainage. E is the drained modulus of a sand and the undrained modulus of a clay.
+* **Options:** stress distribution, immediate-settlement method, flexible or rigid
+  foundation, sublayer thickness, influence-depth ratio Δσ/σ'v0, design life, Schmertmann's
+  creep factor.
+* **Criteria:** allowable total settlement and angular distortion (1/x).
+
+## What it computes
+
+| quantity | method |
+|---|---|
+| Δσ under a rectangle | Newmark's integration of Boussinesq, superposed for any point |
+| Δσ under a strip / circle | closed form / exact one-dimensional integral over the polar angle |
+| Δσ under an embankment | exact: Flamant's line load integrated over the piecewise-linear (trapezoidal) load |
+| Δσ, approximate | 2:1 spread |
+| embankment, immediate | Steinbrenner in plane strain, the crest as one strip and each slope as 16 slices |
+| immediate settlement | Steinbrenner F1, F2 on each layer (layered elastic), or Schmertmann (1978) with C1, C2 and the L/B-interpolated influence diagram |
+| primary consolidation | Cr up to σ'p = OCR·σ'v0, Cc beyond it, sublayer by sublayer at each point |
+| secondary compression | Cα/(1+e0)·H·log(t/t_p) from U = 95 % to the design life; Cα·Cr/Cc where the clay stays over-consolidated |
+| time | Terzaghi U(Tv), per clay layer, H_dr = H/2 or H |
+| rigid foundation | settlement of the characteristic point (0.74·B/2, 0.74·L/2; 0.845·R) |
+| angular distortion | (s_centre − s_edge) / (B/2) |
+
+The derivations and their limits are in [docs/theory.md](https://github.com/hdaltuntas/lythos-settle/blob/main/docs/theory.md).
+
+## Figures
+
+Section with the Boussinesq stress bulb · stresses with depth (σ'v0, σ'v0 + Δσ, σ'p and the
+influence-depth criterion) · influence factors at each point with Schmertmann's Iz ·
+cumulative settlement with depth · time–settlement curve · settlement components at each
+point · settlement across the section (the settlement trough under a footing or a fill). Study figures: one-at-a-time sweep, histogram, scatter, tornado.
+
+## Reports
+
+Choose PDF, self-contained HTML or Word in the header and press *Export report…*. The
+report carries the inputs, the stresses, the settlement at each point and in each layer,
+the Schmertmann factors, the consolidation times, the checks, the figures, the warnings,
+the method notes and — if one was run — the study, in whichever language the interface is
+in. All three formats are assembled from one place, so they say the same thing.
+
+## Project files (`.settle`)
+
+JSON. *Save* writes the inputs and the study definition; *Open…* reads them back. Missing
+entries keep their defaults.
+
+## Modules
+
+| file | content |
+|---|---|
+| `lythossettle/stress.py` | Boussinesq (rectangle, strip, circle), 2:1, Steinbrenner |
+| `lythossettle/consolidation.py` | Terzaghi U(Tv) and its inverse, compression of clay, secondary compression |
+| `lythossettle/engine.py` | The settlement analysis: profile, sublayers, points, checks, time curve |
+| `lythossettle/study.py`, `study_plots.py` | Parametric (one at a time) and reliability (LHS / Monte Carlo) studies, statistics, P of exceedance with 95 % CI and β, Spearman sensitivities, CSV / XLSX |
+| `lythossettle/plotting.py`, `plot_style.py`, `render.py` | Matplotlib figures, theme-aware, off-screen |
+| `lythossettle/report.py`, `pdf.py` | Calculation report: one HTML assembly, exported as PDF (reportlab), HTML or DOCX |
+| `lythossettle/forms.py` | Input schema and readers; converts between the interface's flat values and the engine's configuration |
+| `lythossettle/summary.py` | The results as cards and as text, for the browser and the command line alike |
+| `lythossettle/i18n.py` | Every text, English and Turkish, written side by side |
+| `lythossettle/web/` | The local HTTP server, the session, and the browser interface |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q                 # engine against hand calculations, stresses against tables, study, report, web, packaging
+ruff check .
+```
+
+The tests check the stress solutions against published values and brute-force integrals,
+the engine against closed-form cases (a square on an elastic half-space, a one-dimensional
+clay layer, Schmertmann by hand), the report in all three formats, the input schema and its
+file round-trips, and the interface itself — the session and the HTTP layer both, so the
+browser is exercised without a browser.
+
+Releasing to PyPI is described in [docs/releasing.md](https://github.com/hdaltuntas/lythos-settle/blob/main/docs/releasing.md);
+`tools/upload_to_pypi.py` does it from an editor, without a terminal.
+
+## License
+
+[MIT](https://github.com/hdaltuntas/lythos-settle/blob/main/LICENSE) © 2026 Hasan Deniz Altuntaş

lythossettle-0.1.0/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-0.1.0/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-0.1.0/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())