KATAI 2D

Fatih Küçükkarakurt

doi:10.5281/zenodo.20692282

KATAI 2D · Open source · Apache‑2.0 · Windows x64

Geotechnical finite element analysis,
built in the open.

A verification-first 2D finite element engine for soil, structures and groundwater — staged construction, consolidation, seepage, seismic dynamics and safety analysis, driven from the command line or from Python. Every capability is pinned to a closed-form solution, an independent computation path or a published benchmark, and the whole record ships with the source.

Get it on GitHub Install in one line See the verification

Free for commercial and academic use under Apache‑2.0. Windows x64 — a self-contained CLI and a Python wheel.

> katai validate kv-slp-001-griffiths-lane-slope.k2d
warning: materials[0].gamma_sat: "Griffiths-Lane soil": the saturated unit weight
(20 kN/m3) is below the unsaturated one (20.2 kN/m3), which is physically unusual
OK: kv-slp-001-griffiths-lane-slope.k2d satisfies the input contract (1 warning(s))

> katai solve kv-slp-001-griffiths-lane-slope.k2d
phase 1/1: Initial phase
phase 1/1: ok  max|u| = 2.999373e-01 m  FoS = 1.010
  warning K2D-A005  Griffiths-Lane soil: Strength reduction with a
  non-associated flow rule (material "Griffiths-Lane soil": phi = 19.6 deg,
  psi = 0 deg): the factor of safety depends on the mesh and falls as the
  mesh is refined, because the shear band narrows with the elements. …
solved 1 phase(s) in 10.76 s

The Griffiths & Lane (1999) slope — published factor of safety ≈ 0.99. The input file ships in the repository under tests/corpus/; the suite pins this number on every build. The warning is not an afterthought: a factor of safety from a non-associated strength reduction is mesh-dependent, so the run says so where the number is produced rather than in a footnote somewhere else.

152 automated tests — the suite, not a subset, is the specification

57 verification cases in the generated matrix, each declared inside the test that enforces it

26 published benchmarks checked in as plain .k2d input files anyone can rerun

+0.6% on the Prandtl bearing factor N_c = 2+π, solved from the checked-in file

Install

Running in one line.

Two front ends, one contract. The command line is a single self-contained executable; the Python wheel ships the katai package and the same command line — same commands, same documented exit codes.

> irm https://raw.githubusercontent.com/fkkarakurt/katai2d/main/install.ps1 | iex
sha256 verified: af52d11f…282ea6e1
KATAI 2D 0.8.1 (2026-08-19)
  .k2d project file version: 14
  .res results file version: 6
  linear solver backend: eigen
installed -> %LOCALAPPDATA%\Programs\katai2d
open a NEW terminal and run: katai info

The installer downloads the latest release, verifies its SHA‑256 and puts katai on your PATH — no admin rights, no dependencies. Prefer it manual? Download katai2d-<version>-win64.zip from Releases and unzip it anywhere.

> pip install katai2d-0.8.1-cp312-abi3-win_amd64.whl
> python -c "import katai; print(katai.__version__)"
0.8.1
> katai info
KATAI 2D 0.8.1 (2026-08-19)
  .k2d project file version: 14
  .res results file version: 6
  linear solver backend: eigen

One abi3 wheel serves every CPython ≥ 3.12 on Windows x64, from Releases. Plain pip install katai2d from PyPI is planned.

Building from source: a recent MSVC toolchain, CMake ≥ 3.25 and Ninja — .\scripts\build.ps1 -Configure -Test configures, builds and runs the full suite. The portable preset reproduces every published number with no proprietary component. Both release artifacts must reproduce the verification-corpus numbers in a clean environment before they leave the build.

Workflow

From script to verified result.

Model in Python or in a plain text file, validate, solve, read — reproducible end to end, with nothing hidden in a project binary.

Describe the model

A katai.Project in Python, or a plain .k2d file — geometry, materials, water, phases, in fixed units (kN, m, day). One input contract for every front end, pinned byte for byte by the suite.

Validate

katai validate checks the schema and the physics without solving. A readable file with a broken physics contract is an error, not a warning — the engine refuses honestly instead of approximating silently.

Solve

katai solve or prj.run(): staged phases with inherited activation, solved by the same verified engine whichever front end you drive. The exit codes are documented and test-pinned.

Read the results

A .res results file or Python result objects — displacements, stresses, pore pressures, structural forces, factor of safety. The same case solved from the CLI or from Python produces bit-identical results.

import katai

# Units everywhere: kN, m, day.
prj = katai.Project("Griffiths & Lane slope", mesh_size=3.0, auto_refine=False)

soil = prj.materials.mohr_coulomb("Clayey sand", E=1.0e5, nu=0.3,
                                  c=3.0, phi=19.6, gamma=20.2)

# Geometry drawn counter-clockwise, one fixity name per edge.
prj.geometry.polygon(
    [(20, 20), (70, 20), (70, 35), (50, 35), (30, 25), (20, 25)],
    material=soil,
    fix=["full", "horizontal", "free", "free", "free", "horizontal"])

prj.initial(procedure="safety")     # phi-c reduction of the gravity state

job = prj.run()
res = job.results()[-1]
print(f"FoS = {res.fos:.3f}")       # published ~0.99; 1.010 on this mesh

prj.save("slope.k2d")               # the same case, ready for `katai solve`

Complete, commented versions ship under python/examples/ — slope stability, Terzaghi consolidation, staged excavation and an anchored excavation with a wall, an anchor row and interfaces. Each one runs in CTest against its verification band, so an example that stops telling the truth fails the build.

Platform

Everything a 2D geotechnical model needs.

Plane-strain and axisymmetric analysis on a single verified numerical core, open source under Apache‑2.0.

Constitutive models

Linear Elastic, Mohr‑Coulomb with a tension cut-off, Hardening Soil, HS small, Soft Soil and Soft Soil Creep — with drained, undrained (A/B/C) and non-porous drainage types.

Analysis types

K₀ and gravity initial stress, multi-phase staged construction, Biot consolidation with an elastoplastic skeleton, fully coupled flow–deformation, and strength-reduction safety with an honest lower-bound flag.

Seismic dynamics

Acceleration time histories — harmonic, Ricker and stored accelerogram records — with compliant-base and free-field boundaries, Rayleigh damping, optional full plasticity during shaking, and response spectra.

Groundwater flow

Steady-state and transient seepage with free surfaces and seepage faces, confined and unconfined — and honest mass balance, measured to 10⁻¹³ on the Charny dam benchmark.

Structures & interfaces

Plates with elastoplastic M_p/N_p hinges, node-to-node anchors, geogrids, embedded beam rows and zero-thickness Coulomb interfaces.

Higher-order elements

Six- and fifteen-node triangles in plane strain and axisymmetry. The quartic element resolves collapse mechanisms — Prandtl N_c to +0.6% from a checked-in input file.

Design codes

EC7 (EN 1997-1) and TBDY 2018 partial-factor catalogues, applied through material factoring.

Two front ends, one contract

A scriptable CLI (solve/validate/info, documented exit codes) and an engineer-facing Python API — writing the same .k2d contract, pinned byte for byte by the suite.

Applications

Engineered for real geotechnical work.

The analyses that make up the majority of day-to-day practice — on one verified numerical core.

Supported excavations

Retaining walls, anchored and strutted excavations, with staged dewatering, construction sequencing and soil–structure interfaces.

Shallow & deep foundations

Bearing capacity, settlement and load–displacement of footings, rafts and pile rows — in plane strain or rigorous axisymmetry, from service load to collapse.

Slope stability

Factor of safety by strength reduction (φ–c reduction), with the failure mechanism resolved along the slip surface and an honest lower-bound flag when convergence says so.

Seepage & dams

Steady-state and transient groundwater flow, free surfaces and seepage faces, uplift — verified against the classical hydraulics.

Embankments & consolidation

Staged fill on soft ground with time-dependent Biot consolidation, excess pore-pressure dissipation and creep settlement (Soft Soil Creep).

Seismic site response

Earthquake time histories through layered sites with compliant-base and free-field boundaries — including a checked-in El Centro record with its published-spectrum identity.

Python

A whole analysis, in a script.

No input file is required to get started: build the model in Python, run it, and read the answer back. Every object is created in one call and handed back as a handle, and phases switch those handles on and off — which is the whole of staged construction. Materials, geometry, walls, anchors, geogrids, piles, interfaces, groundwater and every phase type are reachable from the same surface, over the same input contract the CLI and the file use.

import katai

prj = katai.Project("Anchored excavation", mesh_size=2.0, auto_refine=False)

# one soil, Mohr-Coulomb: kN, m, day -- units are fixed and stated
sand = prj.materials.mohr_coulomb("Berlin sand", E=3.0e4, nu=0.3,
                                  c=5.0, phi=32.0, gamma=19.0)

# ground, split so the pit can be dug out of it later
prj.geometry.rectangle(0, 0, 30, 12, material=sand, name="Below formation")
pit = prj.geometry.rectangle(0, 12, 12, 20, material=sand, name="Pit")
prj.geometry.rectangle(12, 12, 30, 20, material=sand, name="Retained ground")

# a diaphragm wall with an interface on each face, and a prestressed anchor
wall = prj.structures.plate((12, 20), (12, 6), EA=1.2e7, EI=1.0e5, w=5.0,
                            interfaces="both", name="Diaphragm wall")
anchor = prj.structures.anchor((12, 18), (20, 14), EA=2.0e5, spacing=2.5,
                               prestress=300.0, name="Anchor row 1")

# staging: handles are what phases switch on and off
prj.initial(procedure="k0", exclude=[anchor])
prj.phases.plastic("Excavate to formation", activate=[anchor], deactivate=[pit])

job = prj.run()
print(katai.summary(job, prj))

=== Excavate to formation =======================================
  status        converged
  max |u|       4.329029e-02 m
  diagnostics
    NOTE  K2D-A004
          A structural element ends on a supported node. The reported
          reactions are the soil's contribution only; the element's own
          end force at that support is not included in this build.
  extremes                    min          at                 max          at
    |u|       [  m]             0  (0, 16)                 0.04329  (3, 12)
    u_y       [  m]   -0.00089196  (30, 18)               0.043216  (3, 12)
    sig'_yy   [kPa]       -376.15  (30, 0)                   5.888  (10, 12)
  structural forces (envelope |max|)
    Anchor row 1           anchor    N       195.4 kN/m
    Diaphragm wall         plate     N       325.7 kN/m   M       58.33 kNm/m

Every extreme comes with the place it occurs. “The largest settlement is 43 mm” and “…and it is three metres from the wall” are two different findings; the summary gives both, and a field that is uniform says so instead of inventing a location.
A refusal is an exception, with the engine’s own words. katai.Refusal carries the message verbatim and the stable K2D-* codes, so a script branches on the reason instead of parsing prose.
The script, the file and the desktop application are one contract. prj.save("job.k2d") at any point, and the same analysis opens in the GUI or runs under katai solve — the test suite pins a scripted case byte-for-byte against its checked-in file.
Results are arrays, not screenshots. Displacements, stresses, pore pressures, reactions and structural force envelopes come back as NumPy data, so a parameter study is a for loop.

Verification & Validation

Every claim is backed by a test.

A selection from the generated verification matrix. Three kinds of oracle are admitted: a closed-form solution, an independent computation path that shares no code with the solver, or a published benchmark — self-consistency does not count.

Benchmark	Reference	Result
Prandtl strip footing N_c (φ = 0), from the checked-in file	2 + π	+0.6%
Slope factor of safety (φ‑c reduction)	Griffiths & Lane (1999), published ≈ 0.99	1.010
Rigid strip footing on elastic soil	Giroud (1972) analytic 15.15	+1.1%
Unconfined dam discharge with a seepage face	Charny (1951) exact theorem	+1.02%
Terzaghi 1D consolidation U(T_v), from the checked-in file	Terzaghi series	−1.2% … −0.4%
Resonant column at f₁ — \|u\|, \|a\|	damped SH closed form (Kramer 1996)	−0.6% / −0.2%
El Centro 1940 NS record identity & 5% spectrum	published PGA ≈ 0.319 g and spectral band	0.31882 g · in band
Sparse solve vs dense LU on an independent path	Eigen FullPivLU, no shared code	4.4×10⁻¹⁶

The matrix and its bibliography are generated from declarations inside the tests themselves, and a suite gate fails when they drift. The benchmark inputs are plain .k2d files checked in under tests/corpus/ — anyone can rerun every number on this page.

See the full verification record The matrix in the repository

Scope

What ships today — and what does not, plainly.

A capability that is not verified is not in the product. The left column is in the open-source release now, each item with its oracle in the suite; the right column is stated openly instead of implied.

In the open-source release

Staged construction with PLAXIS-style inherited phase activation; K₀ and gravity initial stress
Linear Elastic, Mohr‑Coulomb (tension cut-off), Hardening Soil, HS small, Soft Soil, Soft Soil Creep
Drained, undrained (A/B/C) and non-porous drainage types
Biot consolidation (elastoplastic), fully coupled flow–deformation, steady and transient seepage
Seismic dynamics: time histories, compliant base, free field, Rayleigh damping, response spectra
Plates with M_p/N_p hinges, embedded beam rows, anchors, geogrids, Coulomb interfaces
Safety (φ–c reduction) with an honest lower-bound flag
EC7 and TBDY 2018 partial-factor catalogues
CLI + Python front ends over one byte-pinned .k2d contract, with a JSON Schema

Not there yet

Three-dimensional analysis — KATAI 2D is two-dimensional by design
A graphical interface — the desktop application is a separate, in-development track
Unsaturated soil mechanics (suction-dependent strength) and liquefaction models
Operating systems other than Windows x64 (the portable, Eigen-only build is the path there)
pip install katai2d from PyPI — planned; the wheel ships from Releases today

The gaps are on the roadmap, not hidden — and nothing lands without the same verification rule: a closed-form solution, an independent computation path, or a published benchmark.

Why KATAI

The numbers, not the marketing.

In most engineering software, the precise numerics behind a result are not yours to inspect. KATAI 2D is built on the opposite principle: an open formulation, open source, and results that are reproducible to a stated tolerance — from input files that are plain, versioned text.

Every capability is locked to its mathematical source — a journal paper, a standard monograph, or published code theory — and is verified against an independent oracle before it is considered finished. Agreement is never manufactured: where a result is sensitive to mesh or to a known limitation of the theory, the record says so, in the same place as the agreement. And when an input cannot be handled correctly, the engine refuses with a clear message — a plausible wrong number is worse than a stop.

Documentation

Read the contract — and the record.

The .k2d input format is documented field by field with a machine-readable JSON Schema, and the verification matrix ships with its full bibliography — all generated from, and pinned to, the code by the test suite, so the documentation cannot drift from the program it describes.

The Scientific Manual documents the formulation baseline and is archived under a citable DOI; an updated edition covering the capabilities added since is in preparation. Alongside it the repository carries the formulation notes each model was built from, the diagnostics catalogue, and the numerical-uncertainty record that states how far a computed number sits from the exact solution of its own equations.

Documentation on GitHub How to cite

cff-version: 1.2.0
title: "KATAI 2D"
type: software
authors:
  - family-names: "Kucukkarakurt"
    given-names: "Fatih"
license: Apache-2.0
repository-code: "https://github.com/fkkarakurt/katai2d"
url: "https://kataigeo.com"
doi: "10.5281/zenodo.20692282"

Citation

Cite it, and cite what it rests on.

KATAI 2D is archived with a persistent DOI, so a result computed with it can be referenced the way any other method is. If you use it in a paper, a thesis or an expert report, please cite the software — and, where a specific number matters, the primary source the verification matrix names for that case.

DOI 10.5281/zenodo.20692282

Resolves to the archived record on Zenodo. A CITATION.cff ships in the repository, so GitHub’s “Cite this repository” button produces the same entry.

@software{katai2d,
  author    = {Küçükkarakurt, Fatih},
  title     = {{KATAI 2D}: an open-source, verification-first
               finite element engine for geotechnical engineering},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.20692282},
  url       = {https://doi.org/10.5281/zenodo.20692282},
  note      = {Source: https://github.com/fkkarakurt/katai2d}
}

Kucukkarakurt, F. (2026). KATAI 2D: an open-source, verification-first
finite element engine for geotechnical engineering [Computer software].
Zenodo. https://doi.org/10.5281/zenodo.20692282

Citing a number rather than the program? Every verified quantity in the matrix carries its own reference — Prandtl, Giroud, Charny, Terzaghi, Griffiths & Lane, Kramer and the rest are listed with their bibliography on the verification page, and the same bibliography is generated into the repository so it can never drift from the tests that use it.

In development

The desktop application.

The engine is open source today. On top of it, a complete modelling, meshing and reporting desktop application is in development — real screenshots from the working build below. It is a separate track and not part of the open-source release; leave your email to hear when the preview opens.

KATAI 2D results view: a contoured field on the deformed finite element mesh with a colour legend.

Results you can defend

Every analysis returns more than a pretty picture. Contoured displacement and stress fields are drawn on the deformed mesh, with a colour legend keyed to the true value range.

Displacement, effective stress, pore pressure and structural force fields
Extreme-value tables and a point inspector for any node
Print-ready engineering report (HTML → PDF) with your title block

KATAI 2D mesh view: an unstructured triangular finite element mesh over a soil domain.

Meshing that adapts to the problem

Generate a quality unstructured mesh from your geometry in one click, then refine exactly where the physics demands it — around walls, piles and loads.

Six- and fifteen-node triangles (quadratic and quartic)
Local refine / coarsen and automatic refinement around structures
Live quality statistics — minimum angle and mean shape quality

KATAI 2D structures view: a supported excavation with a retaining wall and anchors.

Model the whole support system

Soil rarely stands alone. Add the structural elements of a real project and build it in the sequence it is actually constructed.

Plates, anchors, geogrids and embedded beams (pile rows)
Zero-thickness Coulomb interfaces for soil–structure slip
Multi-phase staged construction with stress carried forward

Inside the workspace

A closer look at how it reads.

A few panels from the desktop application — material sets, the phase explorer and the point inspector — so you can judge the workflow before the preview opens.

Stiff clay HS small

E₅₀℅ₙ: 40 000 kN/m²
Eₒₑₐₙ: 40 000 kN/m²
Eᵘᵣ℅ₙ: 120 000 kN/m²
power m: 0.55 —
c′ₒ₋ₛ: 5.0 kN/m²
φ′: 32.0 °
ψ: 2.0 °
γ₋ₐₜ: 20.0 kN/m³

DrainedRᵢₙₜᵣₕ 0.67

Constitutive parameters, with stiffness, strength and drainage in one set.

1 Initial K₀ procedure
2 Wall + dewatering Plastic
3 Excavate to −3 m Plastic
4 Install strut Plastic
5 Excavate to −6 m Consolidation

ΣMstage 0.74

Build the model in the sequence it is actually constructed, stress carried forward.

Node: #4 217
x, y: 12.40, −5.85 m
|u|: 38.6 mm
σ′ₙₙ: −142.7 kN/m²
σ′ₓₓ: −61.3 kN/m²
p₋ₐ₊ₑ₋: 11.4 kN/m²

Click any node for its displacement, effective stress and pore pressure.

About

KATAI Geotechnical Engineering.

KATAI Geotechnical Engineering develops KATAI 2D, a finite element engine for soil and soil–structure analysis. We build computational geotechnics the way we believe engineering software should be built: on established theory, with readable source, and with every result verified against a known solution before it ships. The engine, its command line and its Python package are open source under Apache‑2.0.

Our aim is a tool a practising engineer can trust and a researcher can scrutinise — accurate enough to rely on, transparent enough to defend in a review, an expert report or a paper.

Every capability locked to a closed-form solution, an independent computation path or a published, cited benchmark
The full automated suite runs on every push, on a build with no proprietary component
Honest reporting — refusals over silent approximation; known limitations stated, not hidden

KATAI 2D is designed and written by Fatih Küçükkarakurt, who also maintains its formulation notes and verification record. Work, writing and contact details are at fkkarakurt.com.

KATAI 2D on GitHub fkkarakurt.com Contact

Stay in the loop

Follow the desktop application.

The engine is open source and installable today. The desktop application on top of it is in development — leave your email to be invited to its preview and to hear when new releases land. No payment, no commitment.

FAQ

Questions, answered.

What is KATAI 2D?

KATAI 2D is a verification-first, open-source two-dimensional finite element engine for geotechnical engineering. It analyses deformation, stability, groundwater flow, consolidation and seismic response of soil and soil–structure systems in plane-strain and axisymmetric conditions, driven from the command line or from Python.

Is it really open source, and under what license?

Yes. The engine, the katai command line and the Python package are open source under the Apache License 2.0 — free for commercial and academic use — at github.com/fkkarakurt/katai2d. The verification record (the generated matrix, its bibliography and the benchmark input files) ships in the same repository.

Which analyses and material models are supported?

Constitutive models: Linear Elastic, Mohr–Coulomb with a tension cut-off, Hardening Soil, HS small, Soft Soil and Soft Soil Creep, with drained, undrained (A/B/C) and non-porous drainage types. Analyses: K0 and gravity initial stress, multi-phase staged construction, Biot consolidation, fully coupled flow–deformation, steady and transient groundwater flow, strength-reduction safety, and seismic dynamics with compliant-base and free-field boundaries plus response spectra. Structural elements: plates with Mp/Np hinges, embedded beam rows, anchors, geogrids and Coulomb interfaces.

How is it verified?

Three kinds of oracle are admitted: a closed-form solution stated in full in the test, an independent computation path that shares no code with the solver, or a published benchmark with the primary source cited — self-consistency does not count. The verification matrix and its bibliography are generated from declarations inside the tests, a suite gate fails when they drift, and 26 benchmark input files are checked in as plain .k2d files anyone can rerun. The record is 57 declared verification cases asserted by a suite of 152 automated tests.

How do I install it?

One PowerShell line installs the self-contained CLI: irm https://raw.githubusercontent.com/fkkarakurt/katai2d/main/install.ps1 | iex — it downloads the latest release, verifies its SHA-256 and needs no admin rights. For Python, download the wheel from the GitHub releases page and pip install it; one abi3 wheel serves every CPython ≥ 3.12 on Windows x64. Publication on PyPI is planned.

A name in the documentation is missing on my machine — what happened?

Check the build you actually have: katai info, or python -c "import katai; print(katai.__version__)". Every front end reads one constant, so that number is the build's real identity. The Python surface grew in v0.8.0 — prj.structures (walls, anchors, geogrids, pile rows, interfaces), katai.summary(), the bound structural forces and the flow phases all arrived there — so an earlier wheel will not have them. Upgrading is a fresh pip install of the current wheel from Releases. Files are guarded in the other direction: a .k2d written by a newer build is refused by an older one rather than misread, because each format bump marks an input the older build would have dropped in silence.

What platforms does it run on?

Windows x64 today, for both the CLI and the wheel. The portable build preset runs the entire suite on the vendored Eigen solver with no proprietary component, which is the path to other platforms.

Is there a graphical interface?

Not in the open-source release. A desktop application — modelling, meshing, results and reporting on the same verified engine — is in development as a separate track. Leave your email on the list to hear when its preview opens.

How do I cite it, report a wrong number, or contribute?

A CITATION.cff ships in the repository, and the v0.2 Scientific Manual has a citable DOI on Zenodo. If a number looks wrong, the issue tracker has a dedicated "numerical result" template — state the computed value and the reference with its source, and it will be resolved against primary sources. Contributions follow one non-negotiable rule: a capability that is not verified is not in the product.

Geotechnical finite element analysis, built in the open.