HomiCSx is an open-source Python framework for first-order finite-element computational homogenization on FEniCSx. It connects particulate geometry, periodic-conforming Gmsh meshing, material assignment, linear and finite-strain periodic problems, homogenization, hooks, and essential output in one reproducible workflow.
- Seeded periodic RSA generation for monodisperse or polydisperse circles, spheres, axis-aligned ellipses, and axis-aligned ellipsoids.
- Explicit construction of custom particulate cells, including rotated ellipses and ellipsoids and coated/interphase inclusions.
- Periodic-conforming Gmsh meshes with phase and boundary tags. Triangles, tetrahedra, and tested 2D all-quadrilateral meshes are supported; general 3D hexahedral generation is not.
- Multiphase small-strain linear elasticity and finite-strain homogenization.
- A built-in compressible isotropic Neo-Hookean model, plus user-defined hyperelastic materials through UFL strain-energy functions and matching numerical post-processing methods.
- A finite-strain generalized-Maxwell material with state management.
- Built-in and custom load histories, adaptive stepping, typed hooks, and
macroscopic stress, energy, and Jacobian histories. Finite-difference
tangent histories are available for hyperelastic and generalized-Maxwell
materials as the full row-major derivative
d vec(P) / d vec(F); viscoelastic perturbations replay the current increment from the same previous converged state. This output is not a symmetric Voigt matrix. - XDMF displacement and reconstructed stress/energy output for history-independent materials, suitable for ParaView.
- Wide-format macroscopic CSV output and heterogeneous-safe long-format material-state CSV output.
The higher-level homicsx.stochastic convenience functions and
homicsx.visualization helpers are experimental and excluded from the
publication-supported API.
The random generators use periodic random sequential adsorption and explicitly
store the periodic images needed for boundary-crossing particles. Random
ellipses and ellipsoids are currently axis-aligned because independent random
orientations require a validated orientation-aware collision and clearance
algorithm. For prescribed geometries, Inclusion.orientation supports a 2D
angle or three 3D XYZ rotation angles.
The generator reports nominal volume fraction from original particles. For overlapping/open-cell constructions, the current correction is approximate; that workflow is outside the publication-supported core.
HomiCSx 1.x supports solver execution on one MPI rank. DOLFINx and PETSc still
use MPI internally, but distributed HomiCSx homogenization is deliberately
rejected until cross-rank result consistency is established and continuously
tested. Run workflows without mpiexec.
HomiCSx 1.0.1 is tested on Linux, including Linux under WSL2, with Python 3.10,
DOLFINx 0.9.0, and dolfinx_mpc 0.9.0. The versioned Conda environment is the
authoritative dependency specification. Linux is the verified platform;
native Windows and macOS are not currently in the test matrix.
git clone https://github.com/AmirTahouni/HomiCSx.git
cd HomiCSx
conda env create -f environment.yml
conda activate homicsx_env
python -m pip install --no-deps -e .
python -c "import homicsx; print(homicsx.__version__)"Other dependency versions and native Windows/macOS installations may work but are outside the current verification matrix.
The maintained examples are exercised by the test suite. Start with the compact 2D linear workflow from a source checkout:
python examples/linear_periodic_2d.pyThe examples/ directory contains deterministic, non-interactive
geometry, 2D and 3D linear, hyperelastic, and viscoelastic
workflows. It is the single maintained entry point for runnable examples; the
documentation provides the corresponding narrative tutorials.
The verification documentation summarizes analytical tests, mesh-refinement gates, current-code regression tests, and Abaqus comparisons using models separately constructed by the same author, based on conventional macroscopic stress, strain, energy, Jacobian, and stiffness measures.
- Documentation
- Abaqus comparison suite
- Supported API
- Support and maintenance policy
- Contributing guide
- Citation metadata
- Archived v1.0.1 release
- Zenodo concept DOI
HomiCSx is developed by Amir Reza Tahouni (tahouniamirreza@gmail.com) and distributed under the MIT License.