Mechanics is a Python-first mechanics-of-materials project built around a simple idea:

define the problem in JSON, let the app handle the orchestration.

For the v0.1.0 initial release, the project includes two working packages:

• beams — a universal-ish 2D beam / frame analysis tool
• truss2D — a universal-ish 2D truss analysis tool

Both packages are built on top of anastruct, but they are not throwaway one-off scripts. The goal of Mechanics is to turn a powerful analysis library into something more structured, reusable, and practical for real engineering work through:

• object-oriented package architecture
• CLI-first workflows
• JSON-defined problem statements
• predictable outputs
• plotting orchestration
• test-driven development mindset
• scalability toward richer GUIs later

Many engineers end up writing dedicated scripts for each new beam or truss problem. That works for a single calculation, but it breaks down when you want:

• repeatable workflows
• reusable problem definitions
• cleaner input/output separation
• a command-line interface that others can use
• a path toward graphical tools

Mechanics addresses that by wrapping anastruct inside a more deliberate application structure. Instead of rewriting analysis code every time, you define:

• nodes
• elements
• supports
• loads
• solver / plotting options

in a JSON file, then run the package.

mechanics/
├── beams/
│   ├── in/
│   ├── out/
│   ├── tests/
│   ├── tools/
│   ├── apis.py
│   ├── app.py
│   ├── cli.py
│   ├── core.py
│   ├── design.py
│   ├── io.py
│   ├── utils.py
│   └── RUNS.md
├── truss2D/
│   ├── in/
│   ├── out/
│   ├── tests/
│   ├── tools/
│   ├── apis.py
│   ├── app.py
│   ├── cli.py
│   ├── core.py
│   ├── design.py
│   ├── io.py
│   ├── utils.py
│   └── RUNS.md
└── ...

Each package follows the same general philosophy:

• core.py holds the domain models
• io.py handles parsing and output writing
• app.py orchestrates solving + outputs
• cli.py exposes the workflows cleanly
• tests/ supports TDD and regression protection

Version: 0.1.0

This initial release is already usable.

It is not just a proof of concept. The packages are already solving real engineering-style problems using JSON input files and exporting structured results plus diagrams.

beams is a 2D beam / frame analysis package built around JSON-defined problem statements and powered by anastruct.

The package lets you define beam or shaft-style models in an input JSON file and then generate:

• structure diagrams
• reaction force diagrams
• shear force diagrams
• bending moment diagrams
• displacement diagrams
• structured results in JSON
• tabular outputs in CSV

All heavy numerical analysis and native beam plots come from anastruct, while Mechanics provides the application layer, CLI, I/O model, and output orchestration.

The point is convenience and reuse.

Instead of building a fresh script for every beam, shaft, or support/load arrangement, the user describes the model in JSON and runs the app.

The package has already been used for a real stepped shaft problem, where the model was defined in a JSON file with multiple shaft stations, varying section properties, bearing supports, and gear loads.

That kind of model is useful for investigations such as:

• checking slopes at bearing stations
• checking deflection at gear stations
• deciding whether gear crowning is recommended when deflection becomes excessive

A typical beams problem definition includes:

• named stations / nodes
• element-by-element EA and EI
• support definitions such as hinged / roller / fixed / spring
• point loads, distributed loads, and moments
• plotting options such as DPI, figure size, and chosen diagrams

Because anastruct is a finite-element library with its own sign convention, some plotted diagram orientations may not match the sign convention a user expects from textbooks or internal company standards.

That does not automatically mean the solution is wrong.

It means users should be mindful of the plotting convention when interpreting:

• shear diagrams
• bending moment diagrams
• displacement shapes

truss2D is a 2D truss analysis package built with the same philosophy: universality through arbitrary JSON problem definition.

The package allows the user to define trusses in JSON and generate:

• structure diagrams
• reaction force diagrams
• axial force diagrams
• shear force diagrams
• bending moment diagrams
• displacement diagrams
• structured results in JSON
• tabular outputs in CSV

For classical truss usage, the most important result is usually the axial force picture, but the app is intentionally designed to expose the broader anastruct plotting/solver interface in a consistent CLI workflow.

The emphasis is not on a single hardcoded truss example.

The emphasis is on being able to define:

• arbitrary node layouts
• arbitrary connectivity
• arbitrary support conditions
• arbitrary nodal loads
• arbitrary plotting/output selections

through input JSON files.

That makes truss2D much more reusable than one-off scripts.

The core workflow across the project is:

1. Define the problem in JSON
2. Validate the input
3. Solve from the CLI
4. Export results and diagrams

This makes the problem definition:

• versionable
• reviewable
• shareable
• reproducible
• easy to connect to future GUIs

A problem file typically contains:

• schema
• meta
• units
• nodes
• elements
• supports
• loads
• options

That separation between model definition and execution is one of the biggest strengths of the project.

Mechanics is intentionally CLI-first.

That choice makes the packages:

• scriptable
• automation-friendly
• easier to test
• easier to debug
• easier to wrap later with graphical interfaces

Both packages support workflows such as:

• generate starter templates
• validate an input JSON
• solve and export outputs
• customize plotting behavior
• customize output files

Detailed command examples live in each package’s RUNS.md file.

The primary plotting path is the native anastruct plot pipeline, exported to PNG files.

This gives users direct access to the kinds of visual outputs they expect from structural analysis workflows, while still benefiting from a standardized CLI wrapper.

Typical controls include:

• chosen plot set
• DPI
• figure size
• displacement scale
• optional ZIP bundling of plot files

The package architecture also leaves room for interactive plotting flows, but the native anastruct outputs are the main practical workhorse for the current release.

• JSON-defined beam and shaft models
• support for fixed / hinged / roller / spring supports
• support for point, distributed, and moment loads
• section-by-section EA / EI
• real use on stepped shaft / bearing / gear-deflection style problems
• native anastruct structural diagrams

• JSON-defined 2D truss topology
• arbitrary node/member definitions
• support for common support/load configurations
• axial-force-centered truss workflows
• native anastruct structural diagrams

• OOP package structure
• validation layer
• CLI orchestration
• CSV and JSON output writing
• scalable architecture for future expansion

Mechanics is a good fit for workflows such as:

• beam reaction / shear / moment studies
• cantilever and simply-supported beam checks
• stepped shaft deflection and slope studies
• bearing station slope reviews
• gear station deflection reviews
• truss member force studies
• quick structural what-if runs driven by input JSON files

Create and activate a virtual environment, then install the dependencies you need.

Typical essentials:

python -m pip install anastruct

Optional extras depending on how you use the project:

python -m pip install plotly pytest

Generate a starter input:

python -m beams.cli template --kind beam_simple --outfile beams/in/beam_simple.json

Validate it:

python -m beams.cli validate --infile beams/in/beam_simple.json

Solve it:

python -m beams.cli solve --infile beams/in/beam_simple.json --outdir beams/out/beam_simple_run

Generate a starter input:

python -m truss2D.cli template --kind hinged_example --outfile truss2D/in/hinged_example.json

Validate it:

python -m truss2D.cli validate --infile truss2D/in/hinged_example.json

Solve it:

python -m truss2D.cli solve --infile truss2D/in/hinged_example.json --outdir truss2D/out/hinged_run1

For fuller command cookbooks, see:

• beams/RUNS.md
• truss2D/RUNS.md

Because this project wraps anastruct inside a reusable application layer, you get:

• a stable JSON schema mindset
• reusable CLI commands
• output orchestration
• easier debugging and validation
• more maintainable code organization
• a much cleaner path to future GUIs

In other words, the project is trying to turn ad-hoc structural scripts into a more product-like engineering toolkit.

The project architecture is intentionally set up to grow.

Natural next steps include:

• richer GUI workflows
• more mechanics topics beyond beams and trusses
• more templates and example problems
• more regression tests
• documentation generation
• class diagrams / architecture docs
• deeper engineering post-processing around the raw solver output

• The numerical engine is anastruct, so project capability is partly shaped by what anastruct supports well.
• Beam diagram sign convention should be interpreted with care because anastruct uses its own conventions.
• “Universal-ish” means flexible and reusable, not symbolic-all-knowing magic. The strength of the project is in structured problem definition and practical orchestration.

Mechanics v0.1.0 already delivers a meaningful foundation:

• two working packages
• real CLI workflows
• JSON-defined structural problems
• native anastruct diagram generation
• reusable architecture instead of throwaway scripts
• a practical base for future mechanics tools

If you like the idea of defining structural models in JSON and letting a clean CLI-driven app do the rest, this project is already heading in the right direction.