The computational volume in μic is called the reactor. The reactor is a cubic periodic volume with the following parameters. The XML tag to define a reactor is <reactor>.
This parameter defines the side of the cubic periodic volume. The XML tag for this property is <size>.
This parameter gives the path of the folder in which the output from the programmes are stored. This folder can also define the root folder from where the output of a previous run can be read. The path can be absolute, or relative to the run folder of the programme. The XML tag for this property is <fileFolder>.
This parameter contains a list of paths to folders where the programme should look for input files. The input files includes time step files for the reactor and the particle size distribution files for particle models. The XML tag for this property is <resourceFolder>.
This parameter contains the path of the folder from where the earlier step files have to be copied if the simulation is being restarted from a point in an earlier run. If this path is not defined, the programme will assume that the files are present in the current file folder. (This option can be found in the packing and interactions tab of the GUI.) The XML tag for this property is <copyFromFolder>.
This parameter gives the name of the file which contains a list of the times at which the simulation is done. The time steps in the simulation are the differences between the listed time points. The file should be in ASCII format listing the times as doubles. The XML tag for this property is <timeStepFile>.
Time steps can also be added directly using several sets of minimum and maximum times (both inclusive), with steps between them. The XML tags for this feature are <minTime>, <maxTime> and <step>, to be written in consecutive lines.
In the default mode, the GUI stores the absolute values of all paths in the input XML file produced. If the “use relative paths” option is selected, all paths will be stored relative to the root folder defined in the text field below. XML input files generated this way will be more portable from one computer to another, if all computers have the same directory structure inside the μic root folder. Please note that the paths to external jar files is also made relative. This feature only changes the appearance of the file paths in the XML file and is not defined separately.
The programme provides supports saving 2D slices of the 3D computational volumes at the middle plane along all three directions and an image with depth perception (deep images). The vector information in the computational volume is discretised using the given voxel (or pixel) size. The XML tag for defining the size of the pixels is <pixelSize>. These voxels are then used to generate coloured images. The colours for the materials can be defined. The deep images are created using an algorithm suggested by Cyrille Dunant.
The deep images may or may not be saved, as defined by the user. The depth of the deep images may be defined as the number of pixels which should be included along the depth. The normal images are always stored by default. The XML tag for deep images is <saveDeepImages> (see section 15. ).
The background colour of the images is black by default and can be changed by the user. This colour is used when no material is present at a voxel.The XML tag for this property is <backgroundColor>.
The programme contains an option to recreate the images at a new or the same resolution using the information about the grains stored earlier. The XML tag for this property is <redoPixels> in the input file and recreate images in the Images tab of the reactor in the GUI. If this parameter is set to true the simulation is not repeated and only the information from an earlier run is read.
The reactor overlays a regular cubic grid over the entire three-dimensional volume to increase the speed of the calculations of overlaps. By default, the reactor sets the size of each of the grid element as the diameter of the median initial particle in the system. The user can, however, define the maximum and the minimum number of divisions to make in each dimension. This grid has a significant memory overhead, but around 100 divisions should be possible on most computers. 100 is also the default maximum number of divisions and 1 is the default minimum. The XML tags for these properties are <maxOccupancyPixels> and <minOccupancyPixels>.
The programme contains an option to simulate flocculation on the initial packing of the particles. Apart from the early versions of μic, packing has been implemented as a plugin and a plugin called FlocPacking has been created to provide the functionality described here. However, to keep backwards compatibility with input files created earlier, flocculation parameters can still be defined as described below. For newer input files, it is recommended to use the input method used for other plugin types.
In the flocculation algorithm, the closest particle to each particle is located. The user can define the maximum distance to look for this particle to increase the speed of the calculation. Once the closest particle is found, the first particle is moved closer to the closest particle by a factor defined by the user. This process of bringing particles closer is repeated the number of times defined by the user. In the last step the particles are rotated along the surface of their closest particle thousand times or until a collision with a third particle occurs. This process gives a denser packed structure. This option can be used in two ways discussed in the following subsections. This algorithm is only meant to demonstrate that how it is possible to move particles during packing and is not meant to emulate real processes. In the programme, this process can be found in the method flocculate(GrainList<E> inputSizeList, int steps, double factor, double range) in the class shapes3D.PeriodicVolume.
When this option (called duringDistribution in input XML file) is used, the programme tries to obtain a higher density packing of the particles by bringing the ones already placed in the volume closer together. The programme uses a random parking algorithm, which places particles at random locations in reducing order of their size, in the volume. For each particle a new random location in the computational volume is generated. The position is kept if the particle does not overlap with any other particle, otherwise a new random location is tried. If progressive flocculation is used, the user can define the maximum number of times new random locations will be generated for a particle before the particles already in packed are flocculated.
When the option of progressive flocculation is not used, the final packing obtained is flocculated using the process described above. It must be noted that this process does not actually produce flocculation the way it occurs in real systems, as this process does not attempt to reduce the number of flocks in a system to a minimum.
If this option is selected (called checkNoArea in the XML input file), the free area of the particles is not calculated, possibly saving significant time in the calculations. This option should not be used in cases where overlaps between particles can affect results and the actual volumes of materials are required. As a consequence, this option is not suitable for most cases. It should be only used if the calculation of free surface area is being explicitly called by the user at some other point in the simulation. Any overlaps between particles in this mode will not be calculated so the images and voxels produced will not be correct. This is because although the total amounts of all materials in the system and in each particle will be correct, the radii of the particles will not be adjusted for the overlaps.
This option (called checkIndividualArea in the XML input file) can be used to enable the calculation of the free surface area of the all the particles each time their size is changed. This option can be used when the calculation of free surface at each step of the simulation is not sufficient and the errors are observed to be large. One of the ways of calculating the error is by comparing the real volume and the pixel volume using a high-resolution mesh. This error should be reduced when this option is enabled. A small error is always obtained for all conditions.
This option (called sphereSamplingPoints in the XML input file) can also be used to improve the accuracy of the calculation of free surfaces. The free surface of the particles is calculated by finding the free or covered status of a fixed number of points distributed in a randomly homogeneous way on the surface of all particles. To maintain the vector nature of the programme, the number of points is the same on all particles, independent of their size. By default the programme uses a hard-wired set of 92 points. Although increasing the number of should theoretically increase the accuracy of the calculations, since the distribution is statistically uniform, this behaviour is not guaranteed. The time required for calculations depends linearly on the number of points used for each sphere.
This option (called findCoveringSphere in XML input file) enables the location of an overlapping particle of the same type for all particles. This particle can be used to deposit materials formed from the first particle if the surface of the first particle is completely covered. The covering particle found always has the particle model same as the first particle, and should have free surface, so finding a matching particle is not always guaranteed. In case such a particle is not found, the materials produced are passed to the next particle of that type processed.
Three main types of files, apart from the image files, can be stored using the programme. Information from all particles can be stored in binary files. This information can be reread for regeneration of images, or restarting using the same particle packing. The files are stored in the “grains” folder inside the project folder.
In another format, just the outer radii and positions of all particles can be stored in ASCII. This format can be useful as an input for the analysis of the porosity. The approximate porosity calculation modules of this programme also uses these files. The files are stored in the “porein” folder inside the project folder.
The main information about all the particles can also be dumped in, usually large, ASCII files for manual reading later. These files are stored in the “hydout” folder inside the project folder.
The following block of XML shows the complete definition for a reactor. The line numbers are not a part of the XML format.
<reactor name="myReactor">
<size>100.0</size>
<pixelSize>0.25</pixelSize>
<fileFolder>Data\myReactor\</fileFolder>
<resourceFolder>Data\resources\</resourceFolder>
<copyFromFolder>Data\myOlderReactor\</copyFromFolder>
<timeStepFile>hydsteps40.txt</timeStepFile>
<backgroudColor>black</backgroudColor>
<maxOccupancyPixels>100</maxOccupancyPixels>
<minOccupancyPixels>50</minOccupancyPixels>
<flocculate value="true">
<duringDistribution>true</duringDistribution>
<range>5.0</range>
<factor>0.5</factor>
<cycles>3</cycles>
<maxTrials>10000</maxTrials>
</flocculate>
<sphereSamplingPoints>92</sphereSamplingPoints>
<checkIndividualArea>false</checkIndividualArea>
<checkNoArea>false</checkNoArea>
<findCoveringSphere>false</findCoveringSphere>
<saveHydout>false</saveHydout>
<savePorein>false</savePorein>
<saveGrains>true</saveGrains>
<saveDeepImages depth="128">true</saveDeepImages>
</reactor>
If the time steps can be divided into blocks of time with regular limts, line 6 can be replaced by the block shown below.
<minTime>0.0</minTime>
<maxTime>24.0</maxTime>
<step>1.0</step>
<minTime>26.0</minTime>
<maxTime>72.0</maxTime>
<step>2.0</step>
The above block adds time steps from 0 to 24.0 in steps of 1.0 and then from 26.0 to 72.0 in steps of 2.
One of several options can be chosen in the GUI and the XML file. In the XML file they can be given using the command tag and in the GUI they can be accessed in the edit reactor dialogue.
This option can be found in the “Packing and Interactions” tab in the edit reactor dialogue, and can be enabled using the following line in the XML file.
<command>start</command>
If this option is selected, a new packing is generated and the simulation is carried out.
This option can be found in the “Packing and Interactions” tab in the edit reactor dialogue, and can be enabled using the following line in the XML file.
<command>restart</command>
If this option is selected, the initial packing of particles generated in a previous run is reused to carry out a new simulation. In order to use this option, the initial packing should have been saved in the grains folder using the saveGrains option in the reactor (see section 14). The same command can also be used to restart the process from a later step in an earlier simulation. For example, to restart from step 10 of an earlier simulation, the following command can be used:
<command fromStep=”10”>restart</command>
The information from the earlier run can also be contained in a folder other than the current file folder. This folder can be defined between <copyFrom> tags in the reactor definition (see section 4).
This option can be found in the “Images and Optimisation” tab of the edit reactor dialogue and can be enabled using the following line in the XML file.
<command>redoPixels</command>
If this option is selected, the results from an earlier simulation are used to regenerate images, sections or deep (see section 7). In order to use this option, the initial packing should have been saved in the grains folder using the saveGrains option in the reactor (see section 14).
Some other command options are available only in the XML file. They may be added in the GUI in the future. Some other commands and their functions are listed below. All these commands have to be given between the tags named command.
savePixels: saves all the voxels in a binary files.
pixelsNoHeaders: saves all the voxels in a binary files without the ASCII header at the top of the file.
readStep: can be used to read the information at only one of the steps from one of the previous simulations. The step number has to be added as the value for the attribute step to the command tag. The images and files can be produced for this step.
saveElements: can be used to save nodes and elements of the voxel mesh that can be loaded in an FEM programme.
markNoPores: ensures that the pore elements are not stored in the elements files, to reduce their size. If this case is selected, the program also wraps a single voxel layer of another material around the elements. The ID of this material is the larger of 12 or one more than the number of elements.
doContacts: enables the calculation of contact surface between particles, both by calculating the overlap between the spherical particles and by calculating the contacts between pixels from different particles. This option can be computationally expensive and increases the memory consumption of the pixel mesh by 5 times. The results are stored in the details file.
doVectorBurning: (opposite of noVectorBurning) enables the calculation of the solid fraction of the volume that is connected from one boundary to another. This calculation also counts dead-end branches that may be connected to both ends. The results for each time step are stored in the file connectionMyProject.csv (where MyProject is the name of your project).
doBurning: can be used to save only the pixels that are from the particles that are connected to the boundary, while the others are marked as pores. This option increases the memory consumption of the pixel mesh by 5 times. The connected spheres are identified using vector burning that can be turned on using the doVectorBurning command. This command can be followed by the letters X, Y or Z in capitals to set the direction of burning (e.g. doBurningX or doBurningY).
noBurning: ensures that all pixels from all sphere, and not just the ones from the particles connected to the boundary are saved.