1. PyFEM Installation Guide

PyFEM can be installed directly from the GitHub source. Both the Python API and the command-line interface (CLI) are included.

1.1. Requirements

System Requirements:

Python 3.9 or newer
pip (Python package manager)
Git (for cloning the repository)

Python Dependencies (installed automatically):

numpy - Numerical computing
scipy - Scientific computing
matplotlib - Plotting and visualization
meshio - Mesh I/O operations
h5py - HDF5 file support
PySide6 - GUI framework
vtk - Visualization toolkit

Recommended: Virtual Environment

It’s recommended to install PyFEM in a virtual environment to avoid conflicts with other Python packages:

# Create virtual environment
python3 -m venv pyfem-env

# Activate on Linux / macOS
source pyfem-env/bin/activate

# Activate on Windows PowerShell
pyfem-env\Scripts\activate

# Activate on Windows Command Prompt
pyfem-env\Scripts\activate.bat

1.2. Installation Steps

1.2.1. Method 1: Standard Installation (Recommended)

Clone the repository:

git clone https://github.com/jjcremmers/PyFEM.git
cd PyFEM

Install with pip:
```
pip install .
```
This installs PyFEM and all dependencies, and creates the pyfem and pyfem-gui command-line executables.

1.2.2. Method 2: Development Installation

For developers who want to make local changes and test them immediately:

git clone https://github.com/jjcremmers/PyFEM.git
cd PyFEM
pip install -e .

The -e flag installs in “editable” mode, so changes to the source code are immediately reflected without reinstalling.

1.2.3. Method 3: Direct from GitHub (Advanced)

Install directly without cloning:

pip install git+https://github.com/jjcremmers/PyFEM.git

1.3. Verifying the Installation

After installation, verify that both the CLI and API work correctly.

1.3.1. Checking the CLI

The pyfem command should be available in your terminal:

# Check version
pyfem --help

# Run an example
cd examples/ch02
pyfem PatchTest.pro

Expected output includes solver iterations, convergence information, and generated output files.

1.3.2. Checking the API

Test the Python API in an interactive session or script:

from pyfem import run

# Run a complete analysis
results = run("examples/ch02/PatchTest.pro")

# Access results
print(results['globdat'].state)  # Displacement vector

If both tests complete without errors, the installation is successful.

1.4. Using PyFEM

1.4.1. Command-Line Interface (CLI)

The CLI is the primary way to run PyFEM analyses:

Basic Usage:

pyfem input_file.pro

Command-Line Options:

pyfem --help                    # Show help
pyfem -i input.pro              # Specify input file
pyfem -d state.dump             # Restart from dump file
pyfem -p param=value            # Override parameter

Examples:

# Run a nonlinear analysis
pyfem examples/ch03/cantilever8.pro

# Restart from saved state
pyfem -d results_cycle100.dump

# Override material property
pyfem -i model.pro -p E=210000

1.4.2. Python API

The API allows programmatic control of PyFEM analyses from Python scripts.

Simple Usage - Run to Completion:

from pyfem import run

# Run complete analysis
results = run("input.pro")

# Access global data
globdat = results['globdat']
displacements = globdat.state

# Access properties
props = results['props']

Advanced Usage - Step-by-Step Control:

from pyfem.core.api import PyFEMAPI

# Initialize analysis
api = PyFEMAPI("input.pro")

# Run step by step
while api.isActive:
    # Perform one load step
    api.step()

    # Access current state
    current_disp = api.globdat.state
    load_factor = api.globdat.lam

    # Custom processing or checks
    if load_factor > 5.0:
        print(f"Load factor reached {load_factor}")

# Get final results
results = api.getResults()

# Clean up
api.close()

Loading from Pre-parsed Input:

from pyfem.io.InputReader import InputRead
from pyfem.core.api import PyFEMAPI

# Parse input file
props, globdat = InputRead("input.pro")

# Modify properties programmatically
props.solver.tol = 1e-6

# Run with modified properties
api = PyFEMAPI((props, globdat))
api.runAll()

Accessing Results:

# After running analysis
globdat = api.globdat

# Nodal displacements
displacements = globdat.state

# Nodal coordinates
node_coords = globdat.nodes.getNodeCoords(nodeID)

# Custom output data
for name in globdat.outputNames:
    data = globdat.getData(name, node_list)

# Load factor (for nonlinear analysis)
load_factor = globdat.lam

# Solver status
cycle = globdat.solverStatus.cycle
converged = globdat.solverStatus.converged

1.5. Updating PyFEM

To update to the latest version from GitHub:

cd PyFEM
git pull origin main
pip install --upgrade .

Or if you installed directly from GitHub:

pip install --upgrade git+https://github.com/jjcremmers/PyFEM.git

1.6. Uninstalling

To remove PyFEM:

pip uninstall pyfem

1.7. Troubleshooting

1.7.1. Common Issues

1. “pyfem: command not found”

The executable path may not be in your system PATH. Try:

# Find where pip installed the executable
which pyfem  # Linux/macOS
where pyfem  # Windows

# Add to PATH or use full path
~/.local/bin/pyfem input.pro

2. Import errors

If you get import errors when using the API:

# Reinstall with dependencies
pip install --force-reinstall pyfem

3. VTK or GUI issues

If visualization or GUI doesn’t work:

# Install system dependencies (Linux)
sudo apt-get install libgl1-mesa-glx libxkbcommon-x11-0

# On macOS, ensure XQuartz is installed for GUI

4. Permission errors during installation

Use the --user flag to install in your user directory:

pip install --user .

1.8. Platform-Specific Notes

1.8.1. Linux

PyFEM works out of the box on most Linux distributions. If using system Python, you may need to install python3-venv:

# Debian/Ubuntu
sudo apt-get install python3-venv python3-pip

# Fedora/RHEL
sudo dnf install python3-virtualenv python3-pip

1.8.2. macOS

Install Python 3.9+ using Homebrew if needed:

brew install python@3.11

For GUI support, install XQuartz:

brew install --cask xquartz

1.8.3. Windows

Install Python 3.9+ from python.org
Ensure “Add Python to PATH” is checked during installation
Use PowerShell or Command Prompt for installation
Git for Windows is needed for cloning: git-scm.com

1.9. Running Examples

PyFEM includes numerous examples organized by chapter:

cd examples

# Chapter 2 - Linear elasticity
cd ch02
pyfem PatchTest.pro

# Chapter 3 - Nonlinear analysis
cd ch03
pyfem cantilever8.pro

# View results in ParaView
paraview cantilever8.pvd

Each example directory contains:

.pro files: Input files with problem definition
.dat files: Mesh files
Output files generated after running (VTK, text, plots)

1.10. Development Setup

For contributors and developers:

# Clone repository
git clone https://github.com/jjcremmers/PyFEM.git
cd PyFEM

# Install in editable mode with dev dependencies
pip install -e .

# Run tests
python -m pytest test/

# Check code style
python -m black pyfem/
python -m mypy pyfem/

1.11. Getting Help

Documentation: https://pyfem.readthedocs.io/
GitHub Issues: https://github.com/jjcremmers/PyFEM/issues
Examples: See the examples/ directory
Book: “Non-Linear Finite Element Analysis of Solids and Structures” by de Borst et al., John Wiley & Sons, 2012

1.12. Next Steps

After installation:

Read the Quickstart tutorial
Explore examples in the examples/ directory
Review the pyfem package for module documentation
For development, see the ../develop/overview