Polyhedral Cell Complexes (PCC) Processing Design (DPD code)

Manual version: 0.3.0
First manual release date: 21/09/2022
Current manual release date: 15 January 2023

DPD code is a Materials Design tool intended to design defect microstructure evolution during material processing. The code provides an effective tool for the studies and design of both material microstructures and the effect of the specific material processing routes. Its key feature is the usage of polyhedral cell complexes, which provide a discrete space for designing realistic material defect structures of different dimensions and types.

This is a C++ based software project consisting of several modules working with pre-created Polyhedral Cell Complex (PCC) as the set of its incidence and adjacency matrices represented in a sparse matrix form. The code contains 4 main modules (Processing, Characterisation and Writer), the library of Simulation tasks and the Main module merging everything together, reading configurations and data files, and launching all the other modules. The code works both with 3-complexes (3D) and 2-complexes (2D) BUT - to make results consistent with 2D/3D EBSD scans - it assumes that the grains are 3-cells in the 3D, 2-cells in the 2D case, and so on for grain boundaries and other element types. So it actually replaces definitions of k-cells with ( k + (dim - 3) )-cells, where dim = {2, 3} is the dimension of the problem. In such a way 2-cells are ALWAYS associated with grain boundaries on EBSD maps and are edges for 2D case!

General specifications

The code is written and tested in C++ 17 with the parallelised verson used some features of C++ 20. It is used explicitly Eigen and Spectra libraries which must be downloaded and copied to the directory containing all the STL C++ libraries on the local PC.

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.<\p>

Basic definitions

1. Polyhedral cell complex (PCC):
2. k-Cells:
3. Nodes:
4. Edges:
5. Faces:
6. Volumes:
7. cell number:
8. cell fraction:
9. Ordinary cells: including OCellsNumb or OrdinaryCellNumbs; related variables New2CellNumb
10. Special cells: including SCellsNumb or SpecialCellNumbs
11. sfaces_sequence
12. cfaces_sequence
13. induced topology of the defect structure:
14. State_sVector: If there are several types of special k-cells, only pair of s_faces_sequence and State_sVector describing types for each of them
15. element types: including NewFaceType
16. Normal and reduced Incidence and Adjacency matrices
17. Subcomplex: including Plane cut (a,b,c,D), (reduced (k-1)-complex)
18. k-Skeleton:
19. k-Chain:
20. k-sChain:
21. k-cChain:

More sources on the mathematics related to the Polyhedral cell complexes

An excellent simple introduction to the DCC 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)

Modules

All the modules except the Main consist of the interface and the core parts. The interfaces contains pre- and post-processing of data for this particular module, adapting input from the Main, and manage the function implementations according to the calculation types specified in the configuration file.

1. PCC_Main: include libraries, global variables, reading from files, launching the other modules and simulation tasks;
2. PCC_Processing: assign chains of special k-cells. Essentially, the ultimate goal of the module is to create a list of k-chains (or k-sequences) in the order of appearance of new elements during the consideration process;
3. PCC_Subcomplex: including Plane cut (a,b,c,D), (reduced (k-1)-complex)
4. PCC_Characterisation: performs characterisation of special structures;
5. PCC_Writer: output data in files;
6. Objects.h
7. Support Functions

Main

I. SUBCOMPLEX

II. PROCESSING

Aim: Set new structures (chains) on a PCC elements.

Several generation types deigned for various simulation tasks are available:

One-element generation functions

1. Random choice of a single element
- Use advanced algorithm (C++ …. Library) for random number generation; - Used in all the other more complicated structure generation processes.
2. Random Walker with leaps
- The random walk algorithm choosing travelling across the any k-skeleton (for any k) with some possibility of larger-scale leaps; - Every new regular (without leap) step it choses between the neighbouring k-Cells using the Random choice function( );

Elements’ chain generation functions

1. Random one by one choice of special elements
- Currently allow to set several types of special faces that encoded in the couple of sfaces_sequence (showing the generation order and allowing then easily change the fraction of special faces) and State_Vector (showing the type for each of the faces); - As its output generates set of vectors of s_sequences and corresponding State_Vector - In a binary case (0 and 1 types only) sfaces_sequence is enough for the whole representation of special chains;
2. Strip distributions
3. Max/Min configuration entropy production principle
4. Metropolis-like algorithm with the "energy" minimisation (design module)
5. Ising-like model

III. CHARACTERISATION

IV. WRITER

Objects and Support functions.h

External files

• Configuration file
• PCC sparse matrices and their reading
• Input and output folders

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.

DCC 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: …

DSD code Tutorial

1. Input files and the requested design

All the input files must be in a single folder specified as the ‘input’ directory in the ‘config.txt’ file.

The several sets of combinatorial and topological parameters can be set directly in the file ‘design_request.txt’. Using the Monte-Carlo type of stochastic simulations (Ising-like model), the code creates the chains of special cells arranged to fit all the parameters as close to the requested ones as it is possible in their average.

DCC itself as the set of sparse matrices..

‘config.txt’ file contains

1. ‘input’ directory address
2. ‘output’ directory address
3. the number of calculation points for different values of p
4. the precision of the Monte-Carlo algorithm, and other parameters necessary for the code

‘design_requests.txt’ file containing only the matrix of indices in the form {Nd i(S) i(Sd) i(chi) i(sigma)} where each term can contain any value between 0 and 1, and Nd are the numbers numerating different designs. Each of the index for any variable A is equal to i(A) = A - A_min / A_max - A_min, where A is the current value of the variable, A_min is its minimal possible value, and A_max is its maximum possible value. So, for any variable it’s index evenly distributed between 0 < i(A) < 1. The requirement of a minimum value corresponds to the i(A) = 0, while the maximum - i(A) = 1 instead of X in the request.txt file.

It is important to mention that each design is applied to the whole process, which is the changing of the fraction of special faces p from 0 to 1.

Sparse matrices of the DCC and their names

2. Compilation

What needs to be installed.. Command line commands for compilation of the code..

The code is written and tested in C++17. It works well with CMake 3.23 (cmake.org), g++ compiler (gcc.gnu.org) and CLion IDE (jetbrains.com/clion).

3. Execution

Command line commands to execute the code..

4. Calculation process

What is happening during the calculation process..

5. Output files

The only output of the code is ‘s2c_sequences.txt’ file, which means “special 2-cells sequences”. It contains the list of numbers (the numeration is consistent with the numeration of faces (2-cells) elements) in the discrete cell complex (DCC) possessing the “special” IDs.

In the order of appearance during the considering process..

Project internal structure

The principal files, modules and concepts of the project are

1. the ‘main.cpp’ where all functions launching and the data reading from files occur
and three libraries (or modules) with related functions:
2. DCC_Processing
3. DCC_Characterisation
4. DCC_Writer

These libraries are part of the larger software development and contain a large set of functions, only a small part of which (such as DCCprocessing.h, DCCcharacterisation.h, DCCwriter.h) is used in the DSD code.

1. Processing module

For the whole process of changing the fraction of special faces p from 0 to 1

1. Analyses the request matrix,
2. Using the Monte-Carlo-like random optimisation algorithm, calculates s2c_sequences and saves them in the corresponding matrices,
3. Calculates the purely “random” s2c_sequence as the reference.

2. Characterisation module

1. In this code, this module just calculates the precision matrix of all the requested design parameters: the difference in per cent between the requested (in request.txt) and actual fitted value. If only a single parameter was optimised, the difference is typically minimal, but for several parameters, it can be impossible to fit well simultaneously all of them.

2. Writer module

1. Writes the sets of the designed s2c_sequences as the matrix (each sequence as a separate line) in s2c_design.txt file alongside the random case sequence in a separate s2c_random.txt file.
2. Writes the requested design precision file design_precision.txt containing the matrix similar to the one in the request.txt file, but with the difference in per cent between the requested (in request.txt) and actual fitted value, instead of X.

After the Structural Design tool

The DSD tool is typically just a basic tool for obtaining specific defect configurations on a given DCC. The next two obvious steps are characterisation (which means combinatorial and topological analysis) of the defect structure and simulations of various physical and mechanical processes in the materials possessed with this microstructure.

As it was already mentioned, the design of the processing routes leading to a given microstructure development is of particular interest here. Such a tool provides a unique opportunity for detailed studies of the physical processes supplementing the microstructure evolution.

Applications of DSD tool

1. 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 GNU General Public License v3.0. See LICENSE.txt for more information.

Contacts

Dr Elijah Borodin (Research Fellow in Materials Physics at the University of Manchester; Mechanics and Physics of Solids research group) to Elijah Borodin (any queries regarding the code)