# KATAI 2D

> KATAI 2D is free, open-source two-dimensional finite element software for
> geotechnical engineering, written by Fatih Küçükkarakurt and published by
> KATAI Geotechnical Engineering. Version 0.9.0 (2026-08-31) is released under
> the Apache License 2.0 at https://github.com/fkkarakurt/katai2d and is driven
> from the command line or from Python. Its distinguishing principle is
> verification: 69 declared verification cases against closed-form solutions,
> independent computation paths and published benchmarks, 26 benchmark input
> files anyone can rerun, 207 automated tests. Website: https://kataigeo.com.

## Pages on kataigeo.com

- [Features](https://kataigeo.com/features): every analysis type, element,
  structural element, numerical control and diagnostic; and what is not included.
- [Constitutive models](https://kataigeo.com/constitutive-models): the seven
  soil and rock models with governing equations, parameters and verification.
- [Theory and formulation](https://kataigeo.com/theory): equilibrium, Newton
  iteration and convergence criteria, staged construction, Biot consolidation,
  groundwater flow, strength reduction, dynamics, grid-convergence index.
- [Applications](https://kataigeo.com/applications): slope stability;
  excavations and retaining walls; foundations and bearing capacity;
  consolidation and embankments; groundwater seepage; seismic site response;
  rock and tunnels (Hoek-Brown) — one page each under /applications/.
- [Verification record](https://kataigeo.com/benchmarks): every benchmark with
  its primary source, tolerance band, measured deviation and asserting test.
- [PLAXIS 2D Validation Manual cases](https://kataigeo.com/benchmarks/plaxis-2d-validation-manual):
  four published validation cases rebuilt input for input.
- [Open-source alternative](https://kataigeo.com/open-source-geotechnical-fem):
  how KATAI 2D compares with commercial geotechnical FE programs,
  limit-equilibrium tools and general-purpose FE codes.
- [Python API](https://kataigeo.com/python-api): the scripting surface.
- [Install](https://kataigeo.com/install): download, checksum, first run.
- [FAQ](https://kataigeo.com/faq): 40+ questions answered in full.
- [Desktop application](https://kataigeo.com/desktop): screenshots of the
  graphical application in development (not part of the open-source release).
- [Türkçe](https://kataigeo.com/tr): overview in Turkish.

## What it is

KATAI 2D analyses the core problems of geotechnical practice — supported
excavations, shallow and deep foundations, slope stability, groundwater
seepage, time-dependent consolidation, seismic site response and rock masses —
in plane-strain and axisymmetric conditions. Every analysis is a phase of one
project on one mesh; stresses, pore pressures and structural forces carry from
each phase into the next. Every capability is pinned to a closed-form solution,
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, its bibliography and the benchmark input files
ship in the repository.

## Capabilities (v0.9.0)

- Constitutive models (7): Linear Elastic; Mohr-Coulomb with a tension cut-off
  and a dilatancy cut-off; Hardening Soil; HS small (Masing's rule, and the
  Li & Dafalias dilatancy below the phase-transformation line); Soft Soil; Soft
  Soil Creep; Hoek-Brown (the generalised 2002 criterion, entered as sigma_ci,
  mi, GSI and D rather than as a c'/phi' fit). Drainage types: drained,
  undrained (A), (B), (C), non-porous.
- Analysis types: K0 procedure and gravity initial stress; multi-phase staged
  construction (plastic); Biot consolidation (elastoplastic), ended by time or
  by a target degree of consolidation / residual excess pore pressure; fully
  coupled flow-deformation; steady-state and transient groundwater flow;
  strength reduction safety (phi-c); seismic dynamics.
- Dynamics: acceleration time histories (harmonic, Ricker, stored accelerogram
  records) with compliant-base and free-field boundaries, Rayleigh damping,
  optional full plasticity during shaking, response spectra.
- Elements: 6- and 15-node triangles; plane strain and axisymmetric; automatic
  Delaunay-refinement meshing with a 20 degree minimum-angle bound.
- Structural elements: plates with elastoplastic Mp/Np hinges, embedded beam
  rows, node-to-node anchors with prestress, geogrids, zero-thickness Coulomb
  interfaces.
- Ground data: borehole logs as input; the layer geometry is generated from them.
- Design codes: EC7 (EN 1997-1) DA1-C1, DA1-C2, DA2, DA3 and TBDY 2018
  (static, seismic) partial-factor catalogues, per phase.
- Diagnostics: 37 stable K2D-* codes; an input is never dropped in silence.
  A run reports which convergence criteria it met (global force error, current
  stiffness parameter, local stress-point error).
- Front ends: the `katai` command line (solve / validate / info, documented
  test-pinned exit codes 0/2/3/4/5) and a Python package — one `.k2d` input
  contract (JSON with a JSON Schema, format version 18), pinned byte for byte.

## Not included (stated limits of v0.9.0)

- Three-dimensional analysis (2D by design).
- Liquefaction and cyclic pore-pressure models.
- Suction-dependent strength; the unsaturated flow formulation (van Genuchten,
  Mualem, Bishop chi = S_eff) is implemented but verified only in its saturated
  limit.
- Large-deformation (updated mesh) analysis; discrete jointed rock.
- A graphical interface in the open-source release (a desktop application is in
  development as a separate track).
- Binaries for operating systems other than Windows x64; PyPI publication.
- For Hoek-Brown rock, four analyses are refused rather than approximated:
  undrained (B) and (C), a Safety phase, EC7 design approaches that reduce a
  characteristic strength, and interface strength left at the schema default.
- HS small accumulates strain history as a scalar and does not detect load
  reversals automatically; use the phase option reset_small_strain.

## Python API (v0.9.0) — for writing correct KATAI 2D scripts

Units are FIXED everywhere: kN, m, day (seconds and m/s2 in dynamic phases).
Stiffnesses are per metre out of plane in plane strain; anchors and pile rows
are discrete members and carry a `spacing` [m] that the engine divides by.
Every object is created in one call and returns a handle; phases activate and
deactivate those handles, which is the whole of staged construction. Loads and
structures are active from the initial phase unless excluded there.

```python
import katai

prj = katai.Project("Job", kind="plane_strain", element="tri6",
                    mesh_size=2.0, auto_refine=True)
# kind: "plane_strain" | "axisymmetric";  element: "tri6" | "tri15"

soil = prj.materials.mohr_coulomb("Sand", E=3e4, nu=0.3, c=5.0, phi=32.0,
                                  gamma=19.0, drainage="drained", k=1e-3)
# also: linear_elastic(E, nu) · hardening_soil(E50, Eoed, Eur, c, phi, m=0.5)
#       hs_small(E50, Eoed, Eur, G0, gamma07, c, phi)
#       soft_soil(lam_star, kap_star, c, phi)
#       soft_soil_creep(lam_star, kap_star, mu_star, c, phi)
#       hoek_brown(E, nu, sigma_ci, mi, gsi, D=0.0, psi=0.0, sigma_psi=0.0)
# common keywords: psi, gamma, gamma_sat, k or kx/ky, drainage
# drainage: "drained" | "undrained_a" | "undrained_b" | "undrained_c" | "non_porous"

pit = prj.geometry.rectangle(0, 12, 12, 20, material=soil, name="Pit")
prj.geometry.polygon([(0,0), (30,0), (30,12), (0,12)], material=soil,
                     fix=["full", "horizontal", "free", "horizontal"])
# points counter-clockwise; one fixity name per edge:
#   "free" | "normal" | "horizontal" | "vertical" | "full"
# optional flow=[...] per edge: "closed" | "seepage" | ("head", m) | ("flux", m/day)

prj.water.table(9.0)                    # or prj.water.phreatic_line([(x, y), ...])
load = prj.loads.line_load((5,20), (10,20), qy=-20.0)
prj.loads.point_load((15,20), qy=-50.0)
prj.displacements.line((0,20), (5,20), ux=None, uy=-0.01)
prj.dewatering.well((15,0), (15,12), q=1.6, h_min=2.0)
prj.dewatering.drain((5,10), (10,10), head=8.0)

wall = prj.structures.plate((12,20), (12,6), EA=1.2e7, EI=1.0e5, w=5.0,
                            Mp=0.0, Np=0.0, interfaces="both")
anch = prj.structures.anchor((12,18), (20,14), EA=2e5, spacing=2.5,
                             prestress=300.0, Fmax_tens=0.0)
prj.structures.geogrid((4,6), (20,6), EA=1e4, Np=50.0)
prj.structures.pile((12,20), (12,6), E=3e7, diameter=0.6, spacing=2.5,
                    Tskin_max=0.0, Fmax_base=0.0, connection="hinged")
prj.structures.interface((4,6), (20,6))
# interfaces: "both" | "positive" | "negative" | "none"
# Mp, Np, Fmax_*, Tskin_max = 0 means UNLIMITED, not zero capacity.

prj.initial(procedure="k0", exclude=[anch, load])   # "k0" | "gravity" | "safety"
prj.phases.plastic("Excavate", activate=[anch], deactivate=[pit])
prj.phases.plastic("Load", activate=[load])
prj.phases.consolidation("Dissipate", duration=100.0, steps=50)
prj.phases.consolidation("Until 90%", until_degree=90)        # a PRESSURE ratio
prj.phases.consolidation("Until 1 kPa", until_excess_pore=1.0)
prj.phases.safety("FoS")
prj.phases.transient_flow("Drawdown", duration=10.0, steps=10)
prj.phases.fully_coupled("Coupled", duration=10.0, steps=10)
prj.phases.dynamic("Quake", duration=20.0, steps=2000, wave="record",
                   record=[...], record_dt=0.02, damping=0.05,
                   rayleigh=(1.0, 10.0), compliant_base=True, free_field=True)
# any phase also takes: apply_fraction (Sum-Mstage), design=,
#   water= (scalar y or [(x, y), ...]), tolerance=, load_steps=,
#   max_iterations=, ignore_undrained=, reset_small_strain=
# design: "none" | "ec7_da1_c1" | "ec7_da1_c2" | "ec7_da2" | "ec7_da3"
#         | "tbdy2018_static" | "tbdy2018_seismic"

report = prj.validate()          # input contract, no solve
prj.save("job.k2d")              # the same case, ready for `katai solve`
job = prj.run(on_phase=lambda i, n, name: print(name))
print(katai.summary(job, prj))   # phases, extremes WITH locations, forces, diagnostics

res = job.results()[-1]          # one result per phase
res.ok, res.fos, res.max_disp, res.diagnostics      # fos is -1 if not computed
sf = next(s for s in res.struct_forces if s.name == "Plate")
sf.max_N, sf.max_Q, sf.max_M, sf.yielded, sf.stations   # station: s, x, y, N, Q, M
```

A refusal is an exception, not a return code: `katai.Refusal` carries the
engine's message verbatim, `.report` (field-path issues) and `.diagnostics`
with stable `K2D-*` codes — branch on `d.code`, not on the prose.

IMPORTANT for anyone generating KATAI 2D code: `hoek_brown`, `until_degree` and
`until_excess_pore` require **0.9.0 or newer**; `prj.structures`,
`katai.summary`, `katai.extremes`, `transient_flow`, `fully_coupled`, `design=`
and `water=` require **0.8.0 or newer**. Earlier wheels raise AttributeError or
TypeError. Check with `python -c "import katai; print(katai.__version__)"`.
The displacement reported by a Safety phase is a failure mechanism and has no
physical magnitude.

## Verification (selected; each asserted by a named automated test)

- Prandtl bearing factor Nc = 2 + pi, from a checked-in benchmark file: +0.6%.
- Smooth rigid circular footing (axisymmetric) vs the Cox (1962) slip-line
  collapse pressure 225.6 kPa: 233.9 kPa, +3.7%.
- Strip footing on clay with strength increasing with depth vs Davis & Booker
  (1973) 7.80 kPa: 7.91 kPa, +1.4%.
- Rigid strip footing vs Giroud (1972) analytic 15.15 kN/m: 15.32, +1.1%.
- Griffiths & Lane (1999) Example 1 homogeneous slope, FoS by phi-c reduction:
  1.384 vs the Bishop & Morgenstern charts 1.380 (+0.3%); published FE value 1.4.
  On a nested mesh family (142/568/2272 elements) the factor falls 1.4210 /
  1.3867 / 1.3645 — non-associated strength reduction is mesh-dependent, and
  the program reports this on every such run (K2D-A005).
- Second Griffiths & Lane slope, published FoS ~0.99: 1.010.
- Charny (1951) exact dam discharge: +1.02%, global mass balance 8e-14.
- Terzaghi 1D consolidation U(Tv): -1.2%..-0.4%; |dU| <= 0.0061.
- Consolidation phase stopping at 90% degree: 14.776 day vs 14.566 (+1.45%).
- Hardening Soil oedometer vs the integrated Eoed law: -0.93%.
- HS small unloading heave vs the inverted secant law: -0.14% / -0.30% / -0.72%.
- Soft Soil oedometer: -0.01% (primary), -1.01% / -1.63% (elastic legs).
- Soft Soil Creep, 100 days of creep vs mu* ln(1 + t/tau): +1.81%.
- Hoek-Brown circular tunnel under 28 MPa vs the closed-form elasto-plastic
  solution: 0.59% inside the plastic annulus, 0.72% outside.
- Beam bending: deflection -0.000%, moments +0.00% / +1.04%.
- Prestressed anchor lock-off: 499.919 kN of 500 kN (0.016%).
- Interface sliding block vs Coulomb closed form: -0.59%.
- Resonant column vs the damped SH closed form: -0.6% / -0.2%.
- El Centro 1940 NS record identity: PGA 0.31882 g at 2.02 s; 5% spectrum peak
  2.87x at 0.19 s, inside the published band.
- Sparse solvers vs dense LU on an independent code path: 4.4e-16.
- 69 declared verification cases; 26 benchmark input files checked in as plain
  .k2d files; 207 automated tests; CI reruns the full suite on every push on a
  build with no proprietary component.

## Validation against the PLAXIS 2D Validation Manual (four cases, input for input)

Four problems from the PLAXIS 2D Validation Manual, Version 8 (Bentley
Systems) are rebuilt in KATAI 2D exactly as that manual defines them, each
from a checked-in .k2d file run through the public command line. The PLAXIS
values are published values quoted unchanged (PLAXIS was not re-run; the
programs do not share a mesh — the problem definitions and reference values
are identical). Closed form | PLAXIS 2D published | KATAI 2D:

- 2.1 Smooth rigid strip footing on elastic soil (Giroud 1972), force at
  10 mm settlement: 15.15 | 15.24 (+0.6%) | 15.32 kN/m (+1.1%).
- 2.2 Strip load on incompressible Gibson soil (Gibson 1967), centreline
  settlement: 0.050 m half-space | 0.047 m finite layer | 0.0454 m (-3.4%
  vs the like-for-like finite-layer PLAXIS value).
- 3.1 Bearing capacity of a smooth rigid circular footing, axisymmetric
  (Cox 1962 slip-line, exact 225.6 kPa): 225.6 | 220.0 (-2.5%) | 233.9 kPa
  (+3.7%) — the two programs bracket the exact value from opposite sides.
- 3.2 Strip footing on clay with strength increasing with depth (Davis &
  Booker 1973): 7.80 | 7.86 (+0.8%) | 7.91 kPa (+1.4%).

KATAI 2D is an independent project, not affiliated with Bentley Systems.

## Install

- CLI (Windows x64, self-contained, no dependencies):
  `irm https://raw.githubusercontent.com/fkkarakurt/katai2d/main/install.ps1 | iex`
  or `katai2d-0.9.0-win64.zip` from https://github.com/fkkarakurt/katai2d/releases
  (SHA-256 57147c8a98e8734a9acfb1096668874628e133fdba7a5115f22230d860382032).
- Python: `pip install katai2d-0.9.0-cp312-abi3-win_amd64.whl` (downloaded from
  the same releases page). One abi3 wheel serves every CPython >= 3.12 on
  Windows x64 and ships the `katai` package and the same `katai` command line.
  PyPI publication is planned.
- `katai info` prints: KATAI 2D 0.9.0 (2026-08-31); .k2d project file version
  18; .res results file version 9; linear solver backend: eigen.
- Cost: none. Apache-2.0; free for commercial and academic use; no licence key.

## Citation

Küçükkarakurt, 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 — a CITATION.cff ships in the repository.

## Contact

- Website: https://kataigeo.com
- Repository: https://github.com/fkkarakurt/katai2d
- Author: Fatih Küçükkarakurt — https://fkkarakurt.com
- Email: katailabs@gmail.com