Features
Everything a two-dimensional geotechnical model needs, and nothing unverified.
KATAI 2D release 0.9.0 is a complete plane-strain and axisymmetric finite element engine: nine analysis types, seven constitutive models, five kinds of structural element, groundwater flow, earthquake dynamics and two design codes — all reachable from a command line, a Python package and a documented text file. This page is the full list. One rule governs what is on it: a capability that is not verified is not in the product.
01 · Analysis types
Nine phase types, combined freely in one project.
Every analysis is a phase. Phases follow one another on the same mesh, each starting from the stresses, pore pressures and structural forces the previous one left.
| Phase type | What it solves | Verified, e.g. |
|---|---|---|
| K0 procedure | Geostatic initial stress from unit weights, the water table and K0; no displacement is generated. The standard start for horizontal ground. | residual ~5×10−13 kPa (KV-NUM-003) |
| Gravity loading | Initial stress by switching on self-weight, for sloping ground and non-horizontal layering where K0 does not apply. | — |
| Plastic (staged construction) | Elastoplastic deformation under a change of geometry, load, water or support. Activation is inherited from the previous phase; a stage may be applied in part (ΣMstage). | heave +0.0% (KV-EXC-001) |
| Consolidation | Coupled Biot consolidation with an elastoplastic skeleton, ended by time or by a target degree of consolidation or residual excess pore pressure. | U(Tv) −1.2 … −0.4% (KV-CON-002) |
| Fully coupled flow–deformation | Transient groundwater flow and deformation solved together, for water levels that change faster than the soil can follow. | saturated limit +0.00000% (KV-STR-008) |
| Groundwater flow, steady | Confined and unconfined seepage with free surfaces and seepage faces. | discharge +1.02% (KV-FLW-001) |
| Groundwater flow, transient | Time-dependent flow for drawdown, filling and dewatering. | — |
| Safety (φ–c reduction) | Factor of safety by strength reduction, as an initial procedure or after any phase. | FoS 1.384 vs 1.380 (KV-SLP-002) |
| Dynamic | Time-history analysis with Newmark integration, absorbing boundaries and Rayleigh damping. | resonance −0.6% / −0.2% (KV-DYN-002) |
Phase options available on every type: a per-phase water level, a design approach, the tolerated error, the number of load steps, the iteration limit, the fraction of the stage to apply, “ignore undrained behaviour”, and “reset small-strain history”. All of them are written into the project file, so a result can be reproduced from the file alone. See the theory page for the equations behind each type and the applications pages for worked problems.
02 · Elements and meshing
Quadratic and quartic triangles, on a mesh with a guaranteed minimum angle.
- 6-node triangles (quadratic displacement) for everyday deformation analysis, and 15-node triangles (quartic displacement) where collapse loads and factors of safety matter. The quartic element deforms without volumetric locking, which is what an incompressible plastic mechanism needs: Prandtl’s Nc to +0.6%.
- Plane strain for long structures and axisymmetry for circular footings, shafts, single piles and deep tunnels — a separate formulation with the hoop strain carried and integration weighted by the radius.
- Automatic unstructured meshing by Delaunay refinement (Ruppert 1995) with a 20° minimum-angle bound, for which termination is guaranteed. The mesher reports whether the bound was met on every element, and the suite checks that report against the geometry (KV-DIA-002).
- Automatic refinement around structures and loads, a coarseness factor per structural member, and local refinement of regions and lines.
- Nested refinement that splits every triangle into four, preserving angles and shared nodes exactly (KV-NUM-006) — the basis of grid-convergence studies.
03 · Structural elements
Walls, anchors, reinforcement, piles — and the contact between them and the soil.
| Element | Carries | Limits |
|---|---|---|
| Plate | N, Q, M — walls, linings, slabs, rafts | plastic moment Mp and axial force Np |
| Anchor / strut | axial force between two points; prestress | tension and compression capacity |
| Geogrid | tension only — reinforcement and geotextiles | tension capacity Np |
| Embedded beam row | pile rows sharing load with the soil | skin friction and base resistance |
| Interface | slip and gapping between soil and structure | Coulomb strength via Rinter |
Force diagrams are returned at stations along each member, with the envelope over the phases and a flag when the member has yielded. A value of zero for a capacity means unlimited, not zero capacity.
Verification: beam deflection −0.000% and moments +0.00% / +1.04% (KV-STR-003); anchor lock-off 0.016% (KV-STR-001); interface sliding −0.59% (KV-STR-002); pile-row capacity −0.00% (KV-STR-004); geogrid tension +0.000% (KV-STR-005).
04 · Groundwater
Water as a field, not as a line on a drawing.
- Phreatic level as a table or a polyline; a different water condition per phase.
- Steady and transient flow with prescribed head, prescribed flux, closed and seepage-face boundaries.
- Wells (discharge with a minimum head, or infiltration) and drains (prescribed head, optionally vacuum).
- Impermeable and semi-permeable barriers along walls and interfaces.
- Anisotropic permeability; van Genuchten retention and Mualem relative permeability above the water table.
- Undrained loading with excess pore pressure, and its dissipation by consolidation.
Details and benchmarks: groundwater flow & seepage.
05 · Dynamics
Earthquake time histories with absorbing boundaries.
- Harmonic, Ricker and recorded input motions; the record is stored in the project file.
- Compliant base with the motion applied as the incident wave; free-field lateral boundaries.
- Rayleigh damping by target ratio at two frequencies.
- Linear dynamics, or full plasticity during shaking.
- Response spectra of computed motions.
Details and benchmarks: seismic site response.
06 · Ground data
Borehole logs are an input.
Every ground model starts from borehole logs, and redrawing them as polygons by hand is the slowest step of setting a model up and the easiest place to put a number in the wrong row. It is also the one error nothing downstream can catch: the mesher meshes the wrong ground, every phase converges on it, and the answer is a correct solution to a model nobody meant.
In KATAI 2D a borehole is a position, a level for each layer boundary and a water head. The layer polygons and the phreatic line are generated from the logs by a stated interpolation — so a reviewer sees the logs a model was built from, not only the drawing. The interpolation is verified to round-off against values computable by hand (KV-GEO-001).
07 · Design codes
Partial factors, applied per phase.
A design approach is a property of a phase. The engine applies the catalogue’s partial factors to the material strengths, so a serviceability phase and its ultimate-limit-state check live in the same project.
| Code | Approaches | Key |
|---|---|---|
| EN 1997-1 (Eurocode 7) | DA1 Combination 1, DA1 Combination 2, DA2, DA3 | ec7_da1_c1 … ec7_da3 |
| TBDY 2018 (Türkiye) | static and seismic | tbdy2018_static, tbdy2018_seismic |
A design approach that reduces a characteristic strength is refused for Hoek–Brown rock, where “the” strength parameter to factor is not defined by the code.
08 · Numerical controls
A run says what its answer satisfied — not just that it “converged”.
“Converged” usually means one global force residual fell below a tolerance. That is a necessary condition and a weak one: a model can balance its forces while individual stress points sit far from their own material law. KATAI 2D computes, applies and reports a family of criteria, and a results file carries which of them were met:
- The global force error, normalised so that it tightens as a mechanism forms.
- The current stiffness parameter — 1 for a fully elastic step, falling towards 0 at collapse.
- The local error at each stress point — the distance between the stress a point carries and the stress its constitutive law would return — and the count of inaccurate points.
On the verification case the local and global measures differ by a factor of 63 000 when only the global one is enforced (KV-NUM-013), which is the size of what a global-only test can miss.
What can be controlled, per phase
- The tolerated error and the maximum number of iterations.
- The number of load steps, and the fraction of the stage to apply.
- The tolerance of the constitutive integration (substepping under an error estimate).
- The time step of consolidation and dynamic phases, or a target state to stop at.
What the answer does not depend on
- The linear solver: every sparse backend agrees with a dense LU factorisation on an independent code path to 4.4×10−16 (KV-NUM-002).
- The front end: the CLI’s results file equals the in-process solve bit for bit; a scripted project equals its checked-in file byte for byte.
- The stopping tolerance, within its useful range: a factor of safety of 1.421021 at 10−3 through 10−8 (KV-NUM-007).
- The number of load steps, for Hardening Soil: 0.020% between 10 and 160 increments (KV-NUM-009).
Where the answer does depend on a numerical choice — the mesh, for a strength-reduction factor; the time step, for consolidation — the dependence is measured with the grid-convergence procedure of Roache (1994) and Celik et al. (2008), built into the engine and verified against manufactured data (KV-NUM-004). The record is numerical-uncertainty.md.
09 · Diagnostics
An input may be used differently from the way it was written — but never in silence.
37 stable diagnostic codes. A warning means the analysis answers your question on a model that is not literally the drawn one. A refusal means the object would have contributed nothing, and the run stops.
| Code | Severity | Raised when |
|---|---|---|
K2D-G003 | refusal | A distributed load does not land on the mesh — drawn above the surface, outside the model or across a hole. The run stops: with self-weight in the model, the settlement would have hidden the missing load completely. |
K2D-G004 | warning | A distributed load is applied over only part of its drawn length. Both lengths are given; equilibrium reflects the applied part. |
K2D-G009 | warning | A wall or interface is not on mesh edges and has been bonded instead. |
K2D-A004 | note | A structural element ends on a supported node; the reported reactions are the soil’s share only. |
K2D-A005 | warning | Strength reduction with a non-associated flow rule: the factor of safety depends on the mesh. Quote it with its mesh. |
K2D-M005 | note | A phase asked to reset small-strain history, and no material in the model has one. |
An unattached load is refused rather than warned about on purpose. If the run continued it would converge, report a plausible displacement field, and answer a model you did not draw. A wrong answer that looks right is worse than no answer. The property is tested, not promised: one fixture per code perturbs a single field of a benchmark and checks both the diagnostic and global equilibrium of what remains (KV-DIA-001).
Codes are stable — never reworded, reused or retired into something else — so a script can branch on them. The full catalogue is docs/diagnostics.md.
10 · Front ends
One input contract, three ways in.
- The
kataicommand line —solve,validate,info— a single self-contained executable with documented, test-pinned exit codes, for batch runs and CI. - The Python package — build a model in a few lines, run it, read results as NumPy arrays. See the Python API.
- The desktop application — drawing, meshing, staged construction, results and reports on the same engine; in development as a separate track. See desktop.
All three read and write the same project file, and the suite pins them against each other.
Formats
Plain text you can diff, review and archive.
- .k2d
- The project: JSON, version 18, documented field by field, with a JSON Schema. Units fixed: kN, m, day.
- .res
- The results: version 9, including which convergence criteria each phase met.
- Versioning
- A newer build reads every older file. An older build refuses a newer file instead of misreading it — each version bump marks an input the older build would have dropped silently.
- Stability
- New keys are written only when used, so a project that touches no new feature produces the same bytes as before.
Specification: k2d-format.md · all documentation.
Scope
Not included — stated rather than implied.
- Three-dimensional analysis. KATAI 2D is two-dimensional by design.
- Liquefaction and cyclic pore-pressure models.
- Suction-dependent strength. The unsaturated flow formulation is implemented but verified only in its saturated limit.
- Large-deformation (updated mesh) analysis.
- Discrete jointed rock. Rock is an equivalent continuum (Hoek–Brown).
- Operating systems other than Windows x64 as released binaries; the engine builds and runs its whole suite with no proprietary component, which is the route to other platforms.
- A graphical interface in the open-source release. The desktop application is a separate track.
pip install katai2dfrom PyPI. The wheel is downloaded from the releases page today.
Nothing lands on the list above this one without the same rule: a closed-form solution, an independent computation path, or a published benchmark — 69 of them so far.
Install it, run a published benchmark, check the number.
KATAI 2D is free under Apache‑2.0, installs in one line and ships the input files of the benchmarks it is verified against. The fastest way to judge it is to rerun one.