New Features and Improvements

None

Bug Fixes

• Implemented handling of neglectable imaginary parts (tolerance with respect to machine epsilon of input type) stemming from spectral decomposition of symmetric second-order tensors;
• A new boolean parameter can be optionally passed to spectral_decomposition() to drop imaginary parts of eigenvalues and eigenvectors when these are close to zero (set False by default);

New Features and Improvements

• Avoid overhead cost by default when performing matrix condensation.

Bug Fixes

Some bugs were fixed in this release version:

• Fixed bug when building first Piola-Kirchhoff stress tensor for Paraview output under finite strains.
• Avoid state update kinematic post-processing when state update fails under finite strains.
• Fixed bug (missing argument) when writting voxels output file under finite strains.
• Fixed bug when checking adaptivity input parameters type.
• Fixed clusters strains initial iterative guess under clustering adaptivity.

New Features and Improvements

• JOSS publication. This release follows the review process of the Journal of Open Source Software.

• Improved documentation. Included CONTRIBUTING.md and CODE_OF_CONDUCT.md files.

Bug Fixes

None

New Features and Improvements

• Renaming Python package to cratepy. Given that there is already a Python package called crate deployed in PyPI, CRATE's Python package was renamed to cratepy.

Bug Fixes

None

New Features and Improvements

• Included workflow to host Sphinx documentation on GitHub Pages. Documentation is deployed automatically whenever there is a push to the master branch.

Bug Fixes

• Hosting README.md images as GitHub gists. Images in the README.md file are now read from GitHub gists in order to be successfully displayed in PyPI.

New Features and Improvements

This Pull Request includes a massive development of CRATE and yields the first version deemed ready for its open-source release. Besides many new code features and improvements, the new version includes a proper src/ layout, all the required Python package distribution files, a complete Sphinx documentation (with automatically generated API) and a directory of benchmarks. The coding style has also been improved, closely following the PEP8 guidelines, and a Flake8 configuration file has been included for the sake of coding style uniformity and automatic checking.

Below is a brief list of the main developments introduced in this version:

• Massive OOP refactorization.

• Extension of CRATE to finite strains.

• Enrichment of available matricial and tensorial operations and procedures.

• Improvement of FFT basic scheme implementation.

• Enrichment of homogenized strain-stress output file.

• Implementation of St.Venant-Kirchhoff anisotropic hyperelastic constitutive model.

• Implementation of general isotropic elasticity.

• Initial guess of RVE effective elastic tangent modulus available from the offline-stage.

• ASCA equilibrium problem converted to total formulation (total strains as primary unknowns).

• ASCA equilibrium formulation without the far-field strain was removed.

• Add input data file option to keep the reference material properties constant.

• The spatial discretization file directory can now be specified as a calling argument.

• Removed some clustering algorithms implementations (not validated).

• Removed some optimizers implementations (not validated).

• Add new output file with the CRVE effective tangent modulus.

• Add new input data file option to minimize the output to the essential.

• Generalized Swift strain hardening law to Nadai-Ludwik.

Bug Fixes

Several bugs were fixed during this development cycle.

Description

A whole new Adaptive Clustering-based Reduced-Order Modeling (ACROM) framework is now implemented and working smoothly. Several new output files are now available and the output during the analysis is significantly enriched. New tools include a analysis rewinding framework and the storage of the CRVE final clustering. An important locking strategy is implemented to deal with the self-consistent scheme convergence issues. Additional progress is made in the OOP refactorization of the initial code modules. Some important bugs have been found and are now fixed.

New Features and Improvements

• Offline-stage flexibility. It is now possible to perform the offline-stage elastic analyses with Links (Finite Element Method) but the online-stage with CRATE. This procedure relies on a constitutive model source conversion that converts the material-related objects (properties and models) between Links and CRATE. This option is left turned ON by default, given that the SUCT procedures are more efficiently performed in CRATE (avoiding Python-Fortran-Python bridges). Later this option should be revisited and implemented in a more robust way.

• Reference material properties locking strategy. The admissibility of the self-consistent iterative solution is now always evaluated. If not admissible, then the last converged increment reference material elastic properties are considered to obtain an accepted solution. In the following macroscale loading increment, the self-consistent scheme is performed again as usual, being the solution admissibility evaluated again. The admissibility tolerance of the Young modulus is made relative to the reference material elastic tangent in the first increment and empirically set as 2.5%.

• New reference material output file. A new output file contains data associated with the reference material, namely its properties, incremental farfield strain and convergence metrics (normalized norm of difference between the incremental farfield strain tensor and incremental macroscale load strain tensor, normalized self-consistent scheme cost function, normalized norm of difference between the effective tangent modulus and reference material tangent modulus). Two output modes are available: 'iterative' outputs the reference material quantities at every self-consistent scheme iteration; 'converged' outputs the reference material quantities that converged at each macroscale loading increment (default).

• New voxel material-related output. A new output file contains material-related data at the voxels level every converged macroscale loading increment. This file is output as described in the section Voxel material-related output of CRATE's input data file and stored in the post-processing directory. A material-related quantities computer class is now available to compute standard strain and/or stress related quantities.

• CRVE effective tangent modulus. Implemented new option to compute the CRVE effective tangent modulus based on the solution of a linear system of equations (same results, more efficient). This computation is now only performed after convergence of the equilibrium Newton-Raphson iterative scheme. In addition, implemented validation procedure of the cluster strain concentration tensors (available for the SCA far-field formulation).

• Generalized Adaptive CRMP (GACRMP). Implemented a new user-defined parameter that is a threshold of the number of clusters of a given material phase. As soon as this threshold is surpassed, adaptivity procedures are locked and the material phase remains static up to the end of the simulation.

• Clustering adaptivity output file. A new output file contains data associated with the clustering adaptivity, namely the number of clusters and clustering adaptive step of each adaptive material phase, and several time measures (partial and total clustering adaptivity step times).

• Clustering adaptivity summary. A clustering adaptivity summary is now presented in the '.screen' file at the end of the online-stage., containing the partial and total number of clusters, and the partial and total computational times.

• VTK enrichment. Clusters adaptive level is now available for visualization in the VTK output, together with the equivalent von Mises stress and strain.

• Clustering adaptivity trigger. Macroscale loading increment where adaptivity conditions are triggered is now repeated with the new clustering. The alternative strategy, where the clustering adaptivity is performed in between increments, is still left in the code but is deactivated. Together with the new strategy is the option of an improved initial iterative guess for the clusters incremental strain after the clustering adaptivity is performed. The adaptivity manager now keeps count of the number of clustering adaptive steps performed on each macroscale loading increment. It is defined a maximum number of clustering adaptive steps per macroscale loading increment (set to 1, can be later converted to input file optional parameter if need).

• Pool of clustering adaptivity features. The pool of clustering adaptivity features is expanded, accounting for new features as well as the increment and/or norm options.

• Clustering adaptivity criterion class. A superclass AdaptivityCriterion is implemented to implement new clustering adaptivity criteria. Each adaptive material phase is now associated with a given instance of AdaptivityCriterion. The old 'non-spatial' criterion has been renamed 'Adaptive cluster grouping' and has now a dedicated class. A new clustering adaptivity criterion based on the evaluation of spatial discontinuities is implemented.

• Enriched Adaptive Cluster Grouping adaptivity criterion. New optional parameter is_merge_adapt_groups: True if the adaptive cluster groups of the same adaptive level are to be merged, False if each adaptive cluster group follows an independent hierarchy.

• Number of child clusters. Redefined maximum number of child clusters based on parent cluster's volume fraction.

• Power dynamic split function. Implemented dynamic adaptivity split factor power function that allows a proper control of the number of child clusters (set linear by default). Magnitude is now employed to closely enforce the threshold number of clusters by sorting clusters in descending order (prioritizes higher magnitude clusters). Also, a new parameter is implemented for the spatial discontinuities selection criterion, whereby the magnitude associated to the lower valued targeted cluster is multiplied by a given factor comprised between 0 and 1 (default).

• Refinement of execution time summary. CRATE's execution time summary is further refined, being the accumulated post-processing time (both offline and online stages) accounted independently.

• Storing CRVE final clustering. The CRVE final clustering state can now be stored (overwrite) the '.crve' file after the online stage is performed. This procedure is only relevant if clustering adaptivity procedures are considered. Although the clustering adaptivity parameters can be updated in the following analysis, the clustering type of each material phase cannot be changed. If is required to consider a given adaptive material phase as 'static', simply set the associated clustering adaptivity frequency to None. This output can be performed as described in the section Final clustering state storage of CRATE's input data file.

• Cluster labels VTK output. Cluster labels are now relabeled from zero in the VTK output. This new relabeling method only affects the VTK output, maintains the relative position of the existent cluster labels and does not have any effect in static clustering analyses.

• Analysis rewind framework. New analysis rewinding framework that is controlled by two new classes (RewindManager and IncrementRewinder) and that allows the rewinding of the solution to a previously stored state while preserving the CRVE clustering. This framework can be properly used as documented in the section Analysis rewinding of CRATE's input data file, namely by selecting an appropriate rewind state and analysis rewinding criteria.

• OOP refactorization. Object-oriented refactorization of homogenized results output module and VTK output module.

Bug Fixes

• Reference material elastic tangent and compliance. Fixed the update of reference material elastic tangent and compliance tensor in the first SCS iteration after a macroscale loading increment cut.

• GACRMP parent class. Set GACRMP parent class as ACRMP.

• VTK collection file. VTK collection file ('.pvd' file) is now always working, even if the simulation is interrupted or does not converge successfully up to the end. In addition, time steps file path is now relative (VTK/...) so that '.pvd' file keeps working smoothly even when the analysis directory changes.

• CRVE number of clusters. The CRVE class has a new attribute (_base_phase_n_clusters) which stores the prescribed (base clustering) number of clusters for each material phase and that is now used to perform the base clustering. The CRVE attribute _phase_n_clusters is now continuously updated if there are new clusters coming from adaptive procedures.

• Cluster labels of different ACRMP. Cluster labeling was raising errors with two or more adaptive material phases. A new CRVE method has been implemented to get the CRVE maximum cluster label to solve this issue.

• Matrix condensation function. Turned off check validation procedures in matrix condensation function: insane computational costs when dealing with large data matrices!

Description

Implemented a Generalized Adaptive Cluster-Reduced Material Phase (GACRMP).

New Features and Improvements

• Generalized Adaptive Cluster-Reduced Material Phase. Implemented a new type of clustering adaptivity coined Generalized Adaptive Cluster-Reduced Material Phase (HACRMP) that essentially performs the adaptivity of each target cluster by performing the prescribed adaptive clustering scheme (similar to the base clustering scheme for the material phase domain). Taking advantage of the recently introduced CRMP class, which ensured that all the clustering procedures can now be prescribed independently and in a total general way for each material phase, this type of adaptivity is deemed as the most simple and general in the sense that a complete cluster analysis is performed for each target cluster.

• Adaptivity hyperparameters. It is important to remark that no studies have been made yet in order to evaluate the impact or best suited values for the clustering adaptivity hyperparameters (for both adaptivity criterion and adaptivity types). The default values left in the code have been established based on some preliminary examples, but are by no means the optimal values.

Bug Fixes

None

Description

This new release version accounts for a significant improvement of the clustering related code OOP design and brings 2 main improvements: (1) the generalization of the CRVE class as a composition of cluster-reduced material phases (CRMP) and (2) the introduction of adaptive cluster-reduced material phases and associated online clustering adaptivity.

New Features and Improvements

• Massive clustering OOP refactoring. The code structure associated with the Cluster-Reduced Representative Volume Element (CRVE) has been massively refactored with significant changes in the underlying classes and methods. The CRVE has a main class containing all the required public methods and is composed by one or more Cluster-Reduced Material Phases (CRMP).

• Cluster-Reduced Material Phases. A new abstract class (CRMP) has been implemented allowing that each material phase is treated in a truly independent manner. This results in a significant increase of CRATE's flexibility, given that all the clustering procedures can now be prescribed independently for each material phase (clustering algorithm, clustering features, clustering parameters, etc.). The most basic type of CRMP is coined Static Cluster-Reduced Material Phase (SCRMP), meaning that the base clustering computed in the offline stage is kept constant during the solution procedure.

• Clustering adaptivity. Besides the above improvements, CRATE has now the first clustering adaptivity scheme in the world! A coined Adaptive Cluster-Reduced Material Phase (ACRMP) has been implemented as a new abstract class and a particular type of ACRMP, coined Hierarchical Agglomerative Adaptive Cluster-Reduced Material Phase (HAACRMP), has been derived. This ACRMP performs the clustering adaptivity by resorting to an hierarchical agglomerative clustering algorithm and to the underlying linkage matrix. Although it behaves as expected and shows that the idea is feasible, this approach is severely limited due to prohibitive memory requirements associated with the computation of the distance matrix of the base clustering dataset (around 50000 voxels). In addition, a naive non-spatial adaptivity criterion has been developed and implemented in order to select the adaptivity target clusters.

• New keywords. Associated with the new features and improvements is a set of new keywords whose specification is documented in CRATE's input data file in the sections Cluster Analysis Scheme, Clustering Adaptivity Frequency and Clustering Adaptivity Output. The first allows a completely general prescription of each material phase clustering procedures, including the definition of base and/or adaptive clustering schemes (clustering algorithms and clustering features) and clustering adaptivity parameters. The second controls the frequency of the clustering adaptivity analysis of each adaptive material phase relative to the macroscale loading incrementation. Finally, the last switches on the output of data to the '.screen' file associated to each clustering adaptivity step (execution of adaptivity procedures, number of clusters and execution time table).

Bug Fixes

None

Description

Included additional clustering algorithms to compute the Cluster-reduced Representative Volume Element (CRVE) and two algorithms to perform the standardization of the global clustering data matrix.

New Features and Improvements

• New clustering algorithms. Among the myriad of clustering algorithms proposed in the literature, some clustering algorithms have been selected and are now available in CRATE besides the standard k-Means clustering algorithm. These clustering algorithms were added following three criteria: (1) first, their implementation availability in open source packages or repositories, (2) second, their suitability to efficiently handle large datasets and (3) third, their potential to develop advanced clustering-based analysis strategies. In this regard, it is important to remark that the appropriate characterization of the feature data space and clusters shape, and the actual performance of clustering algorithms has not yet been made. Such studies may reveal that some of the clustering algorithms included in this version are in fact not suitable or, in alternative, suggest that additional clustering algorithms are required. The clustering algorithms available in this version are:

  1. K-Means (source: scikit-learn);
  2. K-Means (source: pyclustering);
  3. Mini-Batch K-Means (source: scikit-learn);
  4. Agglomerative (source: scikit-learn)
  5. Agglomerative (source: scipy)
  6. Agglomerative (source: fastcluster)
  7. Birch (source: scikit-learn)
  8. Birch (source: pyclustering)
  9. Cure (source: pyclustering)
  10. X-Means (source: pyclustering)

• Different implementations of the same clustering algorithm are included for non-dependence of a single source and/or to benefit from additional methods available from different sources. Moreover, most of the clustering algorithm's hyperparameters are left with the default values from the original implementation source (i.e., have not been tuned by any means). The choice of a given clustering algorithm is made from the already existent clustering scheme keyword (specification documented in CRATE's input data file in the section Clustering scheme) .

• Clustering data standardization. The global clustering data matrix is now standardized before the cluster analysis procedure through one of two available and commonly used standardization procedures: (1) Min-Max Scaler (default); (2) Standard Normal Distribution Scaler. The standardization method can be prescribed as usual through an associated keyword specification (specification documented in CRATE's input data file in the section Clustering data standardization).

Bug Fixes

• Self-Consistent Scheme. The default self-consistent scheme has been changed to the regression-based scheme and CRATE's input data file documentation has been updated to reflect the optional nature of this parameter.