<!-- aas-journal:Astrophysical Journal <- The name of the AAS journal. -->

---

# Statement of need

Advanced experimental materials science is entering a new era thanks to the performance and availability of tomography allowing full-3D studies, and often 3D-timeseries.

However in the analysis of these advanced measurements, the attractiveness of closed-source and black-box solutions to 3D measurement problems seems to be precipitating a reproducibility crisis in this domain.

A radically open approach to measurement science with the disclosure of analysis tools will allow validation and verification of tools and results, rendering the whole chain more robust.

Furthermore, the hope is that there is a community-driven improvement of the tools with time.

# Summary

Spam, the Software for the Practical Analysis of Materials is a Python library that has evolved to cover needs of data analysis from 3D x-ray tomography work and correlated random fields with mechanical applications.

Spam is first and foremost a measurement package that extends the extremely convenient framework of NumPy [@numpy] and SciPy [@SciPy2020] by providing or accelerating tools for the material- science/mechanics oriented analysis of 2D images or 3D volumes representing field measurements.

Typical uses are either the measurement of displacements fields between images of a deforming sample from which strains can be computed, or the characterisation of a particular microstructure (correlation length or particle orientation).

...

...

@@ -144,7 +148,7 @@ For a displacement field on an irregular grid (for example defined at particle c

Both finite (large) strain and infinitesimal (small) strain frameworks are implemented for both regular and irregular grids.

-`excursions`: toolkit for the excursion set of correlated random fields theory [@adler2008new].

It includes functions that give the analytical predictions of the global descriptors (or Lipschitz-Killing curvatures) of excursions in spaces of arbitrary dimensions [@roubin2015meso; @roubin2016perco] along with the generation of correlated random fields using "RandomFields" in R through `rpy2` [@Ritself; @rpy2; @schlather2013randomfields].

It includes functions that give the analytical predictions of the global descriptors (or Lipschitz-Killing curvatures) of excursions in spaces of arbitrary dimensions [@roubin2015meso; @roubin2016perco] along with the generation of correlated random fields using `RandomFields` in R through `rpy2` [@Ritself; @rpy2; @schlather2015randomfields].

-`filters`: toolkit of 3D filters that provide some functionality missing in `scipy.ndimage.filters` such as the computation of a local hessian, or functions which are slow (such as the computation of a local variance).

...

...

@@ -160,7 +164,7 @@ A wrapper for ITK's morphological watershed [@schroeder2003itk; @beare2006waters

-`measurements`: toolkit implementing the measurement of covariance, porosity and global descriptors (volume, perimeter, surface area, and Euler characteristic).

-`mesh`: toolkit for the creation or manipulation of meshes -- in `spam` tetrahedral meshes are principally used. Meshers based on gmsh [@geuzaine2009gmsh] are used through `pygmsh` and weighted Delaunay triangulation (Laguerre triangulation) is provided through an interface with CGAL [@cgal] -- alpha-shapes are also implemented to help clean up badly-shaped tetrahedra.

-`mesh`: toolkit for the creation or manipulation of meshes -- in `spam` tetrahedral meshes are principally used. Meshers based on Gmsh [@geuzaine2009gmsh] are used through `pygmsh` and weighted Delaunay triangulation (Laguerre triangulation) is provided through an interface with CGAL [@cgal] -- alpha-shapes are also implemented to help clean up badly-shaped tetrahedra.

In addition, a set of projection functions creates meshes able to represent heterogeneities (phases and interfaces of a given meso/micro structure) based on binary or trinary images or continuous fields (level set) with outputs easily convertible to any FE software [@roubin2015multi; @stamati2018tensile].

-`plotting`: toolkit of plotting tools based on `matplotlib` [@matplotlib] for creating complex plots such as a 3D orientation plot.

...

...

@@ -179,6 +183,7 @@ A number of scripts are available to be called from the command line, at the mom

# Technical details

Spam is based on simple Python data types, avoiding complex data structures, and all functions have a reasonable and safe set of default parameters, with required parameters kept to a minimum.

Spam has a number of different use cases:

...

...

@@ -196,6 +201,7 @@ Building on the large number of functions already available in NumPy [@numpy], S

Spam uses `unittest` to check each commit with a coverage of more than 90\% of lines of code covered as of June 2020.

Details of coverage are available [at this address](https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/coverage/).

# Online documentation

The documentation for this project is available online here:

...

...

@@ -210,10 +216,10 @@ There are three main components to the documentation:

- A series of "Tutorials" with longer and more detailed explanations are available, which cover the mathematical/mechanics background of the functions provided, and some longer examples of using the provided tools.

<!-- # Other software available -->

# State of the field

Other software packages exist for material science analysis, such as the popular commercial software Avizo whose closedness makes it unsuitable inspection and therefore trust.

Other open-source packages could be ITK [@schroeder2003itk] which remains quite a complex ecosystem, or ImageJ/Fiji [@imagej2] which is not fully 3D and not perfectly suited to scripting or running remotely.

All of the above have some version of the `label` toolkit which allows discrete objects to be characterised as well as some parts of the `measurements` toolkit.

...

...

@@ -254,7 +260,7 @@ Spam has already enabled research progress on a number of fronts, resulting in t

- @roubin2019colours: Application of Multi Modal Registration to concrete.

- @hurley2019situ: Use of `deformation` toolkit to measure deformation in concrete.

- @wiebicke2020measuring: Use of `label` toolkit for the analysis of inter-particle contacts as well as the `plotting` toolkit to plot the distribution of orientations.

- @stavropoulou2020: Use of `spam-mmr` and `spam-gdic` scripts, and the `mesh` toolkit to measure water absorption in claystone.

- @stavropoulou2020: Use of `spam-mmr` and `spam-gdic` scripts, and the `mesh` toolkit to measure water absorption in claystone.

# Acknowledgements

...

...

@@ -268,4 +274,3 @@ We would like to acknowledge:

for discussions that have contributed to getting spam into its current form.