Polytopal Cell Complex (PCC) Processing Design (CPD code)

Manual version: 0.4.0
Current manual release date: 11 December 2024

PCC Processing Design or CPD code is a software aimed to provide a wholly discrete representation of defect microstructure evolution during the materials processing. But it also has an additional functionality allowing its usage as a design tool for the microstructure optimisation in polycrystalline composite materials. Its key feature is the usage of polytopal (polygons in the 2D case or polyhedrons in 3D) cell complexes (PCCs) as objects of algebraic topology, which provide a convenient discrete space for large-scale design of realistic material defect microstructures of different dimensions, such as point and line defects, surface defects, and different volumetric phases. Such PCCs can be created based on the 2D/3D tessellation of space with the convex polytopes. For instance, the Voronoi tessellation of space realistically imitating grain structure of a polycrystalline material.

An excellent simple introduction to the cell complexes with their various applications is given in the book of Leo Grady and Jonathan Polimeni "Discrete Calculus. Applied Analysis on Graphs for Computational Science" (2010). More rigorous mathematically introduction to the main concepts and methods of combinatorial algebraic topology is given in the book of Dmitry Kozlov "Combinatorial Algebraic Topology" (2008) . An excellent classical introduction to the graph theory is provided in the classical book of Béla Bollobás "Modern Graph Theory" (1998).

For effective use of the CPD code, a clear understanding of several basic concepts, such as Polytopal Cell Complex, state vectors and special sequences of cells is necessary. All these concepts (and much more) are described in the Theoretical Manual. Even more comprehensive discussions of some particular topics with examples can be found in the following publications:

1. S. Zhu, E.N. Borodin, A.P. Jivkov, 2021. Triple junctions network as the key structure for characterisation of SPD processed copper alloys. Materials & Design 198(24), 109352. doi: 10.1016/j.matdes.2020.109352.
2. E. N. Borodin, A. P. Jivkov, 2019. Evolution of triple junctions’ network during severe plastic deformation of copper alloys – a discrete stochastic modelling. Philosophical Magazine 100(4), 467-485. doi: 10.1080/14786435.2019.1695071.
3. E.N. Borodin, A.P. Jivkov, A.G. Sheinerman, M.Yu. Gutkin, 2021. Optimisation of rGO-enriched nanoceramics by combinatorial analysis. Materials & Design 212, 110191. doi: 10.1016/j.matdes.2021.110191.

In this Technical Guidance, only the architecture of the code and practical guidance for its effective use with some examples are provided. Other related stuff, including already created PCCs with the corresponding discrete space tessellations are presented on the Materia software project.

A few necessary definitions

The provided discrete theoretical framework allows to description and analysis of space ordering inside real materials by the well-developed tools of topology, statistics and graph theory.

• All m-cells with values m less than k form a PCC skeleton, and 3-skeleton coincides with the whole PCC
• Additionally to the scalar and vector parameters defined on the PCC cells, any k-cell can be assigned one or several labels characterising its type(s). Hence all the k-cells can be divided into two classes of ordinary (labelled with ID = 0) and special (labelled with ID > 0) cells.
• The whole set of these labels assigned on each type of k-cells form a configuration state which can be expressed by a single state vector encoding all the cell types similar to the widely-known DNA sequences.
• The set of all the state-vectors in a PCC form its structure.
• Three different types of structures can be distinguished: directly assigned by k-cells labelling, induced on the k-cells by the cells of other dimensions (greater or lesser than k) and produced by pre-existing assigned structures as a result of the corresponding kinetic process (composites fracture, as an example).
• The notion of a process can be referred to as the discrete sequence of all consequent states expressed by their state vectors.

The last component of the proposed approach is a function or map relating structural (such as fractions of special k-cells) and physical (time, plastic strain, mass fraction, etc.) characteristics which can be obtained using the particular experimental data.

How to execute the code

This is a C++ based software project consisting of several modules-libraries and the main.cpp file which is considered as a separate module. The code works with pre-created PCC as the set of its incidence and adjacency matrices represented in a sparse matrix form. It is intended to be launched as a CMake project using CMakeLists.txt file. For successful code execution, both the C++ compiler and CMake software must be installed.

The code is written and tested in C++17. It works well with CMake 3.23 , g++ compiler and CLion IDE . It is partly parallelised with the Open MP libraries for its effective execution using simultaneously several cores within one CPU. It is used explicitly the Eigen and Spectra libraries which must be downloaded and copied to the directory containing all the STL C++ libraries on the local PC. As an example, to compile the project in a command line tool one needs to change the working directory (cd command in Linux) to the one containing the project CMakeLists.txt file and then launch CMake as:

cmake -B buildtree
cmake --build buildtree

After that, one needs change the working directory again to the newly created \buildtree and execute the built file like

cd buildtree
 ./PCC_Processing_Design

With the CLion and other IDEs, everything is straightforward: a new C++ project must be created (if it contains its own main.cpp “Hello world!” file by default, it must be deleted or ignored) and then executed. The computational costs of different calculation types, functions and tasks are hugely different: for instance, the component analysis or Monte-Carlo simulations are a very time consuming procedures, while the random generation of special chains are fast.
The code works equally good with 3D and 2D tessellations of space. In the 2D case, there are no 3D polyhedrons (volumes) and 2D polytopes are associated with faces or 2-cells of the corresponding PCC. All the project functions works similarly in these two cases.

Project files

The project directory contains several folders:

• \src — contains all the source files, *.h libraries of the project and the main.cpp file.
• \config — contains all the *.ini files using for the initial definition of parameters governing the execution of the corresponding modules.
• \PCC_examples — contains a few examples of the PCCs created based on the 2D and 3D Voronoi tessellations. A large PCC library is published on the webpage of the Materia software project.
• \data — contains supplementary data files for each of the project modules.

The \src "source" directory contains several subfolders with libraries:

• \lib — contains all the *.h project libraries Each of the modules is placed in the folder with the same name as its own. These subdirectories contains, in their turn, *.h files with the same name as the corresponding module, and a subdirectory named \functions containing *.h libraries with all the functions used in this particular module. Besides, it contains the library SupportFunctions.h with the additional functions used in several modules, measures.h with functions for calculations of various structural measures, and another library Objects.h as the only place in the project containing all the definitions of the code-specific classes. The subdirectory \ini contains the code-specific readers of the project's *.ini files which nedds to be amended at their any significant changes.
• \task — contains all the additional user-defined tasks written as separate functions and included in the main.cpp file. These functions became active in the mode "TASK" instead of the "LIST" of the [simulation_mode] option in the main.ini file.
• \other — contains additional external libraries such as the simple mINI reader of the *.ini files.

Project modules by their *.ini files

The main part of the “user interface” contains a few *.ini files governing the behaviour of each of the modules. Among them:

1. Main
Provides a common “environment” for all the other project parts. Currently, it is the only .cpp file compiling in the project (see CMakeLists.txt), including all the other project libraries. All the variables, names and PCCpaths are defined here and then it calls all the other modules marked “ON” in the main.ini file.
2. Processing
The central part of the code - generates labelling of a PCC k-cells of different dimensions according to some governing principles.
3. Characterisation
Takes as its input the state_vectors (for assigned, imposed and induced types of faces) as its input and performs different characterisation tasks to output an object of the C++ class Processed_Complex containing all structural characteristics of the special cell structures requested in the characterisation.ini file. The syntax of the characterisation.ini file is especially simple: it contains only boolean type parameters with a value equal to 1 means calculation of this particular characteristic, and 0 means that the code will not calculate it.
4. Writer
Takes as its input the object Processed_Complex and performs only the output of various characteristics contained in this object to the “output” directory specified in the main.ini file with the pre-defined names. The writer.ini file also contains only boolean type of parameters with a value equal to 1 means writing these characteristics to the corresponding file, and 0 means that the parameter will not be written.

Some other modules like Multiphysics (stress and energies), Subcomplex (a subdivision of a PCC into subcomplexes), and Kinetic (processes related to state variables and do not determined by changes in the cell types of a PCC) still unfinished and are under active development. Each of the modules is a *.h library of the corresponding functions written in C++ and, in their turn, consists of two sub-modules - one governing the code implementation based on the requests written in the corresponding *.ini file, and another one (in the corresponding \functions subdirectory) contains the functions themselves. A couple of other *.h function libraries in the \lib directory like SupportFunctions.h contain many useful functions using in different modules for supplementary simple tasks like reading from files to matrices. For reading *.ini files the code exploits external mINI library.

main.ini

[general]

• “dim = 3” or 2 - is the problem dimension for 3D or 2D space tessellations, respectively.
• “source = … \“ set the path to the directory containing PCC in its algebraic representation as a set of all adjacency and incidence matrices with some additional data about the corresponding space tessellation such as polyhedra volumes, face areas, face normals, etc.
It is important to use “\” symbol at the end of the source path!
• “output=…\” set the output directory for the Writer module - where all the calculation results will be written.
It is important to use “\” symbol at the end of the output path!

[modules]
All the rest in the main.ini file is only the list of all MODULES with the two variants: “ON” - for switching on the module execution, and “OFF” - for switching off the module execution.
There are two different [simulation_mode] of the Main module:
”LIST” - by default, launch all the modules one after another strictly according to the data from *.ini files.
“TASK” - assumes tailored execution of the code using the functions, *.cpp and *.h files included explicitly inside the else if(task) {..} statement in the main.cpp module INSTEAD of the “LIST” mode sequence of modules. The ”task” mode is supposed to provide scientific freedom of the code execution and can ignore any instructions listed in the *.ini files.

Each of the following *.ini files contains an almost similar list of settings for every type of cell in the tessellation and the corresponding PCC: polyhedrons (3-cells), faces (2-cells), edges (1-cells), nodes (0-cells). In the Processing module, any algorithm calculates as its output the lists (vectors) of “special” cells of different types described in the corresponding “state vectors”. The are three distinct sub-modules: (1) assigned structures: the algorithm picks cells and assigns them some type ID (label), writing the cell number in the corresponding special_sequence (s_sequence) vector (example: the random assignment of “special” type for some number of faces); (2) imposed structures: assigned types for low-dimensional (k-1)-cells or higher- dimensional (k+1)-cells according to some specific rule based on the already created assigned structures for k-cells (example: classification of face junctions according to the number of special faces incident to each junction); (3) induced structures: assigned types for the k-cells of the same dimension based on the already created assigned structures for k-cells (example: introducing fractured or cracked faces based on the initially assigned structure of faces containing inclusions).

processing.ini

The file is divided in several parts reflecting the dimensions of the cells:
[polyhedrons]
Containing only instructions for the assignment of the polyhedrons (3-cells) types. The set of parameters for polyhedra is in full analogy (possibly less in their number) with one for [faces]. Please read the detailed description below.
[faces]
Containing only instructions for the assignment of the faces (2-cells) types. Several parameters below define the settings for the Assignment type of Processing module.

• “face_types_number =..” — the number of distinct face types (normally from 0 to 3) where 0 means that there are no special faces and the module does nothing here.
• “pf_mode = ..” — (if face_types_number >0) choose the specific processing type from the list of functions in the /src/lib/PCC_Processing/functions directory.
S — reading from source *.txt file (s_sequence.txt ) the list of special faces (for this particular PCC) created before by some of the processing modes listed below;
• “source = /…/s_cells_sequence.txt” — the path to the *.txt file containing a list of numbers of faces of special types. This “source” affects only S processing mode and does not affect any other parts of the code.
R — simple random choice of new special faces during the assignment process; F — choice of new special faces governing by the maximum configuration entropy production principle (MEPP); D — choice of new special faces governing by the minimum configuration entropy production principle; Cr — determination of new special faces by effective random rotations of grains (applicable only for crystallography-related problems); Cm — determination of new special faces by effective rotations of grains governing by the minimum configuration entropy production principle (MEPP) (applicable only for crystallography-related problems); L — the random choice of new special faces with some restrictions that allow to the creation of elongated chains of special cells, whose lengths are normally distributed with the average “mu” and dispersion “sigma”.
• “pf_index = 0” — supplementary index for more flexibility in the code execution, it does not affect anything in the default mode;
The fractions from 0 to 1 for three possible face types specified above in the face_types_number parameter in their order. It is the fractions of special faces which will be assigned by the PCC_Processing module. If there is only one special type, only fmax_fraction1 should be above 0, face_types_number =1, and all the rest fractions will be ignored.
• fmax_fraction1 = 0.9
• fmax_fraction2 = 0.0
• fmax_fraction3 = 0.0
The following statements set parameters for the Induced type of Processing module and for “historical” reasons called cracked faces. By default, there is a possibility to set only one type of such induced faces. This part of the Processing module is always following (in execution time) after assignment one, and, by definition, uses the assignment face types for calculation of the corresponding list of induced faces type.
• “crack_types_number = ..” — similarly to the face_types_number set the number of types and currently only two options are allowed: 0 - there are no induced faces, and 1 - means that the induced part of the Processing module is “on”.
• “cf_mode = Km” — similarly to the pf_mode set the specific mode of the choice of induced faces.
Km — currently only one mode of the “kinematic fracture” is allowed.
• “cfmax_fraction = …” — similarly to the fmax_fraction parameters for assigned face types it sets the fraction of induced faces (in the range from 0 to 1).

[edges]
Containing only instructions for the assignment of the edges (1-cells) types. The set of parameters for edges is in full analogy (possibly less in their number) with one for [faces]. Please read the detailed description above.
[nodes]
Containing only instructions for the assignment of the nodes (0-cells) types. The set of parameters for nodes is in full analogy (possibly less in their number) with one for [faces]. Please read the detailed description above.
Finally, the [distribution] is a very special category relevant for the only case of the elongated chains of special cells, whose lengths are normally distributed with the average “mu = ..” and dispersion “sigma = ..”. It does not affect any other processing modes.

characterisation.ini

The characterisation module is divided in several "labs" [polyhedrons_lab], [faces_lab], [edges_lab], [nodes_lab], corresponding to the each type of k-cells in a 3-complex (PCC) with the similar set of structural characteristics:

• "*l_active = .." - switch on/off the calculations of the characteristics related to the corresponding k-cells (polyhedra, feaces, edges, nodes);
• "config_entropy=.." - calculation of the configuration entropy with its mean (if "S_mean = 1") and deviatoric (if "S_skew = 1") parts.
For the [edges_lab] in addition the calculation of the imposed by faces characteristics of "j_fractions = .." (special edge fractions), "d_fractions = .." (special edge degree fractions), and "analytical = .." (analytical solutions) is posdible.
Finally, [spectra_lab] contains parameters of the corresponding Laplacian spectra. Here

• "calc_steps_numb = .." - set the number of points where the spectrum will be calculated; "laplacians = .." - switch on/off the calculation of the calculation of the corresponding matrix of the combinatorial Laplacian; "laplacians_spectra = .." - switch on/off the calculation of the Laplacian's spectrum (the list of all its eigenvalues); "laplacians_betti = .." - switch on/off the Laplacian's Betti numbers as the dimensions of its null-space (the number of zero eigenvalues).

writer.ini

[sequences]

• "isSequencesOutput = .."
• "isDesignvectorsOutput = .."

[entropic_polyhedrons]

• "isPolyhedronFractions = .."

[entropic_faces]

• "isFaceFractions = .."
• "isConfEntropy = .."

[entropic_edges]

• "isConfEntropy = .."
• "isFractions = .."
• "isDegreeFractions = .."

[entropic_nodes]

• "isNodeFractions = .."

[entropic_analytical]

• "isEdgeFractions = .."
• "isEdgeConfEntropies = .."

[component_analysis]

• "isBetti = .."

Where to take a complex?

The discrete cell complex is a pretty well-known object that originated from the field of algebraic topology, so it can be obtained in many various ways Below is just a concise review of a couple of flexible tools developed in the Mechanics and Physics of Solids research group in the University of Manchester providing DCCs based on Voronoi and a few others tessellations of space by convex polygons.

Tessellations of space provided by Neper software

The Voronoi tesselation provided by Neper supposed to be a dual complex and so all the other tessellations provided by the Neper output with the morphology option -morpho like cube, square, tocta, lamellar, etc. different from voronoi.

Please, see more examples on the Neper webpage.

PCC Generator Tool

Based on the Poisson-Voronoi tessellation of space provided by the Neper software the code creates discrete (combinatorial) cell complex (DCC) as the set of sparse matrices. The DCC Generator Tool generates a sparse representation of matrices: for any matrix element a(i, j) = c, the files of the matrices contain the list of triplets in the form (i, j, c). The enumeration of indices starts from 0, and, for instance, the line "5, 7, 1" in the adjacency matrix A_k means that the k-cell #6 is the neighbour of the k-cell #8. For any incidence matrices B_k, the same triplet "5, 7, 1" means that the (k-1)-cell #6 is on the boundary of the k-cell #8, and their orientations coincide (c = -1 for the opposite orientations).

All the other information on the GitHub page of the project The latest release of the code can be downloaded from the DCGT project page.

FCC and BCC primal slip planes

The package DCC_Structure contains Python modules to build a discrete cell complex (DCC) based on the slip planes of crystal nanostructures (simple cubic, FCC, BCC; HCP not yet available). The script execute.py is a summarised execution of the whole package. It takes as input: …

Applications of DPD code

1. S. Zhu, E. Borodin, A. P. Jivkov, Topological phase transitions of grain boundary networks during severe plastic deformations of copper alloys. Acta Materialia (Under review), 2023.
2. E.N. Borodin, A.P. Jivkov, A.G. Sheinerman, M.Yu. Gutkin, 2021. Optimisation of rGO-enriched nanoceramics by combinatorial analysis. Materials & Design 212, 110191. [doi: 10.1016/j.matdes.2021.110191.](https://doi.org/10.1016/j.matdes.2021.110191)

Acknowledgements

This code has been created as a part of the EPSRC funded projects EP/V022687/1 “Patterns recognition inside shear bands: tailoring microstructure against localisation” (PRISB) and EP/N026136/1 "Geometric Mechanics of Solids: a new analysis of modern engineering materials" (GEMS).

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contacts

Please feel free e-mail to Dr Elijah Borodin (Research Fellow in Materials Physics at the University of Manchester, Department of Solids and Structures) any queries relating with the code.