jihoonkim888/pytopo3d

Purpose and Entry Points

PyTopo3D is a Python framework for 3D SIMP structural topology optimization: it iteratively removes material while satisfying a volume fraction constraint and minimizing compliance. Users enter through the CLI launcher main.py, its argument layer pytopo3d/cli/parser.py, or the package API function top3d in pytopo3d/core/optimizer.py.

Optimization Orchestrator

top3d owns the optimization lifecycle: initialize element densities, apply domain/obstacle constraints, repeatedly solve equilibrium, evaluate compliance sensitivities, filter them, and update densities until tolerance or iteration limit. Its output is the optimized density field, stored internally in (nely, nelx, nelz) order.

• pytopo3d/core/optimizer.py

• pytopo3d/core/evaluator.py

• pytopo3d/core/compliance.py

Finite-Element Analysis Boundary

The physics layer builds the global stiffness system from SIMP-penalized element densities, applies supports and loads, solves nodal displacements, then supplies displacement-derived compliance and gradients to the optimizer. Precomputed assembly indices reduce repeated sparse-matrix setup cost.

• pytopo3d/utils/assembly.py

• pytopo3d/utils/stiffness.py

• pytopo3d/utils/solver.py

The linear-solver boundary prefers PyPardiso when available and otherwise uses SciPy sparse solving. Optional GPU mode uses CuPy/CUDA primarily for solve and filtering workloads.

Density Constraints and Updates

Sensitivity filtering regularizes optimization and prevents mesh-scale artifacts. The optimality-criteria update enforces the volume constraint while respecting fixed voids from obstacles or imported design-space masks. Boundary and axis utilities preserve the public right-handed (x, y, z) convention despite y-first array storage.

• pytopo3d/utils/filter.py

• pytopo3d/utils/oc_update.py

• pytopo3d/utils/boundary.py

• pytopo3d/utils/axis_convention.py

Geometry Ingestion and Domain Masks

Preprocessing converts externally defined geometry into optimizer-compatible voxel masks. JSON describes normalized cube, sphere, and cylinder obstacles; STL input defines or inverts a design space at a chosen voxel pitch. These masks form material-exclusion constraints passed into the optimizer.

• pytopo3d/preprocessing/geometry.py

• pytopo3d/utils/obstacles.py

• pytopo3d/utils/import_design_space.py

Runs, Results, and Observability

The experiment runner binds parsed inputs to a reproducible run: creates result directories, records parameters and metrics, manages logging, and coordinates optional post-processing. This is the main control boundary between CLI/API invocation and compute stages.

• pytopo3d/runners/experiment.py

• pytopo3d/utils/results_manager.py

• pytopo3d/utils/logger.py

• pytopo3d/utils/metrics.py

Visualization and Export

Density fields are rendered for interactive display or captured through iterations for animation. Final designs can be converted to STL via contouring/marching-cubes-style export, with optional mesh smoothing; import/export handles the required x/y layout conversion.

• pytopo3d/visualization/runner.py

• pytopo3d/visualization/animation.py

• pytopo3d/visualization/visualizer.py

• pytopo3d/utils/export.py>

Packaging and Delivery

The project is distributed as a Python package with optional GPU dependencies and supports Conda-based environments. CI validates CPU behavior and packaging; publishing is automated separately.

• pyproject.toml

• environment.yml

• .github/workflows/ci.yml

• .github/workflows/publish.yml