Getting started#

Installation#

loadtracer is not on PyPI yet. Install it from GitHub:

pip install git+https://github.com/structuralpython/loadtracer.git

This also installs papermodels and the analysis packages (PyniteFEA, loadbearing-wall). loadtracer needs Python 3.12 or later.

Your first rundown#

A rundown has three steps. The first is the papermodels workflow, described in the papermodels guide (Getting started).

1. Build the graph with papermodels#

from decimal import Decimal
from papermodels.datatypes.geometry_graph import GeometryGraph
from papermodels.datatypes.joist_models import JoistArrayModel

graph = GeometryGraph.from_pdf_file("sketch_to_scale.pdf", scale=Decimal(1 / 72 * 4))
graph.assign_collector_behaviour(JoistArrayModel, spacing=1.0)

Pass the graph itself to loadtracer. Do not call create_loaded_elements() first: loadtracer calls it, then works through the members in graph order.

2. Give the occupancy pressures#

Each loading area in the drawing names an occupancy (see Marking up drawings). loadtracer needs the pressure of every load case for each occupancy, in the units of the drawing:

occupancies = {
    "residential": {"D": 15, "L": 40},   # psf, since this drawing is in feet
    "roof": {"D": 20, "S": 30},
}

The load case names ("D", "L", "S", …) are yours to choose. Every reaction is reported per load case, and loadtracer does not combine or factor them.

3. Run the rundown#

from loadtracer.load_tracer import LoadTracer

lt = LoadTracer(geometry_graph=graph, occupancies=occupancies)
lt.execute_analyses(artifacts_dir="artifacts")

execute_analyses analyses every member and stores the results on lt. With artifacts_dir, it also writes models.json (every analysis model) and reaction_forces.json (every reaction).

Reading the results#

lt.reactions["FB2.0"]
# {0: {'FX': {'D': 0.0, 'L': 0.0}, 'FY': {'D': -897.35, 'L': -2392.93}, ...},
#  1: {'FX': {'D': 0.0, 'L': 0.0}, 'FY': {'D': -897.35, 'L': -2392.93}, ...}}

lt.reactions["CB0.0"]   # a column at the foundation
# {0: {'FY': {'D': -1812.87, 'L': -4834.32}}}

Reactions are keyed by support index (in order along the member), then by direction and load case. They are the forces on the support, so a gravity rundown gives negative FY reactions. See Results for everything a rundown produces.

Before using the results, check two things:

lt.issues   # input that loadtracer corrected so that the rundown could continue
lt.errors   # members that could not be analysed (with on_error="collect")

loadtracer warns once (a LoadTracerWarning) when there are issues. Read them: they usually point to markups that do not quite meet, such as a load area that extends past the end of a joist.

Next steps#