1. Introduction

Luma is a browser-based finite-element program for the analysis and design of
reinforced-concrete slab systems: suspended flat plates and beams-on-columns,
ground-bearing mats on Winkler soil, pile-supported rafts, slab steps, walls
and edge beams. The model is built as a semantic floor model (slabs,
openings, supports, soil and loads) rather than as raw nodes and elements; the
program generates the mesh, assembles a shell/beam finite-element model, solves
it on the Go server, and renders the results in 3D in the browser.

This chapter covers what the program does, its architecture in enough detail to
use it correctly, the units/sign conventions used throughout the manual, the
user interface, the solver limits, and the shortcuts.

1.1 What the program does

Three model modes

Every floor model is in exactly one mode, chosen automatically by what you
draw (FloorModel.mode):

Deleting the last pile returns the model to slab_on_ground (if soil zones
exist) or suspended. Soil and pile modes are not combined - a mat-on-piles
model is modelled as pile_supported, optionally with a soil zone for bearing
display; the piles are the actual support.

Analysis chain

semantic floor model  →  mesh generation (Go)  →  FE assembly & solve (Go)  →  results (browser)
   slabs, loads,           MITC4 quads /            dense or sparse CG,          contours, diagrams,
   supports, soils         CST+BCIZ triangles        cracked/long-term loops     tables, reports

The mesh and solve run on the server (/api/projects/:id/analysis-model then
/api/projects/:id/solve); the browser keeps the semantic model, renders
results and performs the reinforcement design arithmetic (flexure, shear,
cracking, punching).

1.2 Model size and solver limits

The solver is sized for typical floor-by-floor design work, not for very large
global models. Limits are enforced with clear messages:

A mesh is rejected during generation if a single slab projects more than 5,000
nodes, or if the total exceeds it:

slab "S1": mesh size 0.25 projects 6120 nodes, above the 5000-node build limit - use a larger mesh size

Practical guidance:

• 0.5–1.0 m mesh is usual for a flat plate; use 0.25–0.5 m near punching
  columns only if you accept the node budget.
• An 8 × 8 m bay at 1.0 m gives ~81 nodes and 64 quads; a 30 × 30 m floor at
  1.0 m gives ~961 nodes and 900 quads. The limit is reached at roughly a
  60 × 80 m floor at 1.0 m mesh - split very large floor plans into separate
  projects or coarsen away from the region of interest.
• Dense direct solution is used up to ~2,900 free DOF. Larger models switch to
  a sparse preconditioned CG/BiCGSTAB solver automatically; both are reported
  as luma_fem in the results summary (hover the row for the exact method).

1.3 Axes, signs and units

Axes

• X and Y are the plan axes. X runs to the right, Y runs "up the page" in
  plan.
• Z is vertical and positive upwards. Slab elevations, pile head/tip
  elevations, wall heights and deflections all use Z.
• The vertical axis is fixed to Z; models with vertical_axis set otherwise
  are rejected (semantic slab generation currently requires Z as the vertical axis).
• The viewport uses Z as vertical (world Y internally) - the grid lies in the
  plan plane.

Signs

If a result looks mirrored vertically (e.g. moments appear hogging where you
expect sagging), check the load signs first: an area load entered as q = −3
acts upwards.

Units

The internal model is SI: lengths in metres, forces in kN, pressures in kPa,
moments per width in kN·m/m, stresses in MPa, subgrade modulus in kN/m³. The
Settings → Units tab controls display only; every field converts on entry.

Two unit systems are preset: SI (Metric) and Imperial Units. Changing
the system switches every kind at once; individual dropdowns then override one
kind at a time. Display units travel with the project file, so a model saved in
kip/ft reopens with imperial displays.

1.4 The workspace

Sidebar (left)

• Project tab - the project tree: projects, folders, drag-to-reorder,
  right-click menu (Open, Rename, Duplicate, New Folder, Delete). The active
  project shows a dot; each row shows a n nodes · e elements badge.
• Model tab - the model tree grouped by type: Slabs, Openings, Columns,
  Walls, Beams, Drop panels, Piles, Soil zones, Strips, Vertical plates, Grid
  lines, Measurements, then a Loads parent with Area/Point/Line sub-groups.
  Rows select entities (Ctrl add/toggle, Shift range), × deletes, and a
  selection bar offers Delete/Clear.
• Dragging the splitter resizes the sidebar; double-click resets it.

Top toolbar

Results pane (right)

Opens with the ▶ result plots: Result Set selector, then sections
Deflections, Stress & Moments, Strain, Steel Reinf., Support
Reactions, Beams, Columns, Piles, Walls, Strip Results.
The exact buttons and their meanings are catalogued in
Chapter 5.

Properties pane

Select anything to edit it: every field applies immediately, with Apply/Delete/
Deselect buttons. Multi-selection opens a bulk editor with per-type chips
and "(Mixed)" placeholders. See §2.12.

Modals

All dialogs (tools, settings, load entry, reports) are draggable by their title
bar and clamp below the title bar, so you can park them out of the way.

1.5 Keyboard shortcuts

There is no undo/redo. The Properties pane, bulk editor and load tables are the
way to correct a value; a wrong action (delete, slice) must be redone by
editing the geometry again. Duplicate the project before risky edits if you
need a checkpoint.

1.6 Settings, storage and files

Settings has six tabs - General, Appearance, View, Grid & Snap, Design, Units.
Save as Default stores the current preferences as the app-wide startup
defaults; Restore Defaults clears them. Projects may override settings by
carrying their own: display units, grid spacing/colour, design code and design
parameters, node display and contour style all travel with the project.

Where things live:

Opening a project always clears the analysis results - they are not stored in
the file. Re-run the analysis after opening.

1.7 How to work (recommended order)

1. New project → name and folder. The design code's standard load cases
   (SW/SDL/LL) and combinations are created automatically.
2. Settings → Design - set code, f′c, fy, covers, bar, limits. These stamp
   onto the model's design_params when you apply.
3. Materials - pick grades from the Material Library, or define custom
   grades (project or global scope).
4. Draw the slab regions at their real elevations.
5. Place openings, drop panels, steps (vertical plates).
6. Place supports: columns, point supports, piles, walls, edge beams.
7. Draw a soil zone for mats.
8. Define loads: cases, combinations, then point/line/area loads and wall
   top loads; switch on Self Wt where appropriate.
9. Draw design strips over the column and middle strips, or let the program
   propose centre strips and add them.
10. MESH → CHK → fix anything the validator and mesh checker report.
11. Run Analysis for the cases/combinations you need; read the summary.
12. Inspect results - deflection, moments, bearing, reactions - and sanity
    check equilibrium.
13. Design: required-steel maps, strip sizing, punching, crack width.
14. Report: punching summary/report, charts, PDF/print; export the project.

Steps 2–3 and 9 can be revisited at any time; any geometry change marks the
solved results stale until you re-run.

1.8 Conventions in this manual

• Bold marks a UI control by its exact label.
• Code font marks a value, field name, key or message text.
• Field tables give: label, unit, default, valid range, and behaviour.
• Worked numbers in examples come from the built-in verification library and
  can be reproduced with the models in
  Chapter 8.
• "Not implemented" boxes state the current limits honestly so you do not
  look for a feature that is not there.

1.9 Current limitations

Know these before relying on the program:

Analysis scope

• Linear-elastic statics only - no modal, dynamic, buckling or thermal
  analysis.
• Soil springs act in tension too unless the zone is Compression only, in
  which case the solver iterates uplift gaps automatically. Pile contact stays
  two-way. Keep the resultant within the mat footprint unless gaps are
  modelled (see §7.1).
• Walls and line supports accept vertical springs only (Kz); no horizontal
  soil pressure.
• No moment redistribution, no second-order effects.

Modelling

• Openings must be axis-aligned rectangles fully inside one slab.
• Column stubs are meshed straight; inclined columns are not supported.
• Slabs must be flat polygons in plan; each slab has one thickness (steps are
  modelled with vertical plates).
• There is no undo/redo, copy/paste or mirror for loads or geometry.
• The floor plan is meshed with quads by default; triangles are available but
  thinner for the same node budget.

UI

• The Clear All buttons in the slab load dialogs remove that load type for
  the whole model, not just the current case.
• The After analysis show preference is currently overridden by a hard
  switch to the deflection view after a slab run.
• The DXF endpoint exports the legacy frame model only (empty for slab
  projects); see §9.5.

1.10 Verifying the program itself

Every formula and solver feature is benchmarked against closed-form solutions.

• Verification publishes the tables, the error of every
  benchmark, and how to re-run them from the terminal. The 13 benchmark
  models also ship as JSON project files in web/projects/verification/;
  import one with Import from File, run the analysis and compare against
  the published values. (A dedicated verification page is planned.)

If a result disagrees with an independent hand calculation, reproduce the
nearest verification model first; if it matches there, the difference is in the
model rather than the solver.

→ Next: Chapter 2 - Modelling