(1)Defining user customisable elements
1 Defining the reactor (Reactor)
1.4 Copy from folders (String)
1.6 Relative paths and root folder
1.9.1 High density packing using progressive flocculation
1.9.2 Flocculating final packings
1.12 Number of sampling points on surface of particles
1.13 Locating neighbourhood spheres for distribution
1.15 Example setup of a reactor in the XML file
2 Defining materials (Material)
2.6 Inner (boolean) and Variant (Material)
2.7 Discrete (boolean) and HostMaterial (Material)
2.11 Example setup of a material in the XML file
3 Defining particle models (ModelGrain)
3.3 Initial particle size distribution (String)
3.3.1 Cumulative particle size distribution
3.3.2 Differential particle size distribution
3.3.3 Mono-disperse particle size distribution
3.3.4 Rosin-Rammler particle size distribution
3.4 Example setup of a ModelGrain in the XML file
4.6 Example setup of a reaction in the XML file
5.1 Clean start with new packing
5.2 Start from stored packing or earlier simulation.
Defining user customisable elements
This file is an excerpt from the documentation for µic available online. This chapter describes how different elements can be defined using the GUI and in an input XML file. All the parameters that can be defined for each element type have been described here and the last sub-section for each element type shows an example block of XML input with all the parameters.
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 (see section 1.5) and the particle size distribution files for particle models (see section 3.3 on page ). 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 (see section 5.2). 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 (see section 2.10). 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 1.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.
The user has to define all materials, including the reactants, products and the unreactive materials in the system. Some other materials may have to be defined to store buffers or to serve as intermediate products. lndividual parameters and their meaning are listed below. The titles of the following subsections show the names of the parameters and the class or type of the parameter is given in parentheses after the name. The XML tag for defining materials is <material>.
This field defines the case-sensitive name of the material. Materials have to be assigned a unique name. In the GUI, creating a new material with the same name will replace the earlier material. This property is defined using the attribute “name” with the <material> tag.
This field defines the unique index of the material. The user may define ids of materials to control the order of processing and listing in output files. The id is an optional attribute. The value has to be an integer greater than zero and should be unique. lds are automatically assigned to the other materials in no particular order. This property is defined using the attribute “id” with the <material> tag.
This field defines the “base” density of the material. Although this is the default density of the material, a DensityVariation plugin can be defined to vary this density. It is assumed that the volume of the materials defined in the reactions is based on this density (see section 4.3). The XML tag for defining this property is <density>.
This field defines the rate of diffusion of ions through this material. This value can be used by plugins. This parameter should not be a field in the material and should be defined in a plugin, but has been kept for convenient definition of plugins. If a diffusion plugin has not been used, this value can equally well be used for any other purpose! The XML tag for defining this property is <diffusivity>.
This field defines the fraction of the computational volume occupied by this material at the beginning of the simulation. For example, if a material occupies half the volume in the beginning, this value has to be set to 0.5.
This field is true if this material can be formed only inside the original bounds of the particles. This implies that if this material is produced in a reaction where another material from the same particle is consumed, the volume of this material produced can not be more than the volume of the reactant material from that particle.
If a material is defined to be inner, a variant material for this material has to be defined. Since the inner material can only occupy the space within the original boundaries of the particle, any amount of this material produced beyond this limit is transferred to the variant material, which can either increase the size of its own particles, or transfer this amount to another form due to a change defined in a reaction. The XML tags for defining these properties are <inner>, <hasVariant> and <variantName>.
Materials can be classified as discrete or diffuse. Diffuse materials are assumed to be uniformly mixed in discrete materials. Only discrete materials can be hosts for diffuse materials and each discrete material can host several diffuse materials. For example the user can use the names of the host materials to define layers in particles (see section 3.2). The averaging of the amounts of the materials is done at the level of each particle.
If a material is not defined to be discrete, a host for this material has to be defined. Only discrete materials are drawn in the images produced by the programme. The XML tags for defining these properties are <discrete> and <hostName>.
Note: A material can be present only in one of the layers of only one of the particle models. If a material is required to be present in several particle types, several materials and rule for inter-conversion or distribution have to be defined.
If this parameter is set to be true, the material is defined to be present “universally”, implying that it is not present in a layer in any of the particles. The material can still have an initial and current amount and buffers for reactions, and can be used as reactant or product (see section 4.3). The XML tag for defining this property is <universal>.
Note: All universal materials have to be defined to be discrete.
As most reactions entail consumption and production of materials, the phase present at one of the pixels of a discretised computational volume may change with time. Also, since the size of spherical particles only represents a circumsphere, many points inside this circumsphere may not belong to that particle and may come from a layer in another particle. This means that rules to change the phase in the pixels may have to be defined. To do that, a list of other discrete materials that a material is allowed to replace due to reaction in an image can be defined. In all cases, the programme tries to guess the correct settings for this parameter. The XML tag for defining this property is <replace>.
This parameter defines the colour of the material in images produced by the programme. If a string is passed for this parameter, the programme tries to match the string with English names of colors and hexadecimal RGB definitions. If a colour for a discrete material is not defined, a random colour is assigned. The XML tag for defining this property is <color>.
The block of XML below shows an example setup for a material
<material id="2" name="myMaterial">
<density>2.0</density>
<diffusivity>1.0</diffusivity>
<inner>true</inner>
<universal>false</universal>
<discrete>false</discrete>
<hostName>myOtherMaterial</hostName>
<hasVariant>true</hasVariant>
<variantName>myThirdMaterial</variantName>
<initialAmount>0.30</initialAmount>
<color>red</color>
<replace>anotherMaterial</replace>
</material>
If the material is discrete (line 6), line 7 (hostName) can be omitted. If the field hasVariant (line 8) is false, line 9 (variantName) can be omitted. For automatic detection of the materials to replace, line 12 can be omitted.
Particle models (or ModelGrains) define the concentric arrangement of materials in same and different particles. Any number of particle types can be defined to accommodate all the materials. The XML tag for defining particle models is <modelGrain>.
Every particle model has to be given a unique case-sensitive name. In the GUI, creating a new particle model with the same name will replace the earlier particle model. This property can be defined as the attribute “name” with the <modelGrain> XML tags.
Concentric layers of discrete materials can be defined to be present in a ModelGrain. Since diffuse materials are assumed to be mixed with the discrete materials, the layers can only contain discrete materials. All non-universal discrete materials have to be present in one of the ModelGrains and any material can be present only in one of the layers of one of the ModelGrains. Layers can be added using the XML tag <layer>.
The file-name of the file containing the initial particle size distribution of this particle type is assigned to this parameter. The XML tag for defining this property is <filePSD>. This file can have one of the several different formats, as listed in the following subsections.
In the first possible format, each line of this file should contain a diameter (double) followed by the fraction of the powder by volume that is smaller than this size (double), separated by space or tab. Although the diameters can be listed in any order, if the diameters are listed in ascending order, the fractions listed should be in ascending order as well. The programme renormalises the fractions assuming that 100% of the powder is smaller than the largest diameter listed. The word “Cumulative” (without quotes) can be optionally provided on the first line of the file to denote this format. The distribution will be assumed to be linear between the provided points.
In the second possible format, similar to the first format, each line of this file should contain a diameter (double) followed by the fraction (double) of the volume of the powder present that is of this size, separated by space or tab. The diameters can be listed in any order. In most practically observed particle size distributions, a peak in the fraction values is observed for one of the diameters between the first and the last listed diameters exclusive. This format can be automatically recognised if such is the case. The word “Differential” (without quotes) can otherwise be put on the first line of the file to denote this format. The distribution will be assumed to be linear between the provided points.
A powder can be defined to be mono-disperse (having all particles of the same size) using the third file format. In this format the file should contain only one line of data followed by a line-break. This line should contain the diameter of the particles followed by any arbitrary number, preferably 1.0, , separated by space or tab. This format can be automatically recognised if only a single line of text. The word “Single” (without quotes) may otherwise be optionally included on the first line of the file to denote this format. The number of particles is rounded to the nearest integer calculated from the total initial material of the materials present in the particles and the size of these particles.
A powder can be defined to have a particle size distribution as defined by a Rosin-Rammler function using the fourth file format. In this format, the word “Rosin-Rammler” (without the quotes) is given on the first line. The median diameter of the distribution (dm) is given on the second line. The distribution width is given on the third line of the file (wd). The fraction (f) of the powder below a certain diameter (d) is given by the function below.
(1)
The list of diameters at which the fractions are to be calculated are then listed on different lines on the input. The diameters can be listed in any order. The fraction below the smallest diameter is assumed to be zero and that below the largest diameters is assumed to be 100%. The distribution is assumed to be linear between the listed diameters.
The following XML block shows the setup of a ModelGrain the XML input file.
<modelGrain name="myGrain">
<layer>myInnermostMaterial</layer>
<layer>mySecondMaterial</layer>
<layer>myThirdMaterial</layer>
<filePSD>psdfile.txt</filePSD>
</modelGrain>
All conversion between different materials have to be defined as reactions. Consequently, all the reactions defined do not necessarily require to be actual chemical processes in the system and can be used for many different purposes. The XML tag for defining a reaction is <reaction>.
Reactions have to be assigned a unique case-sensitive name. In the GUI, defining a new reaction with the same name replaces the earlier reaction. This property can be defined using the attribute “name” in the tag <reaction>.
The reactions can be arranged in the order they are required to be implemented. This order is important as it might affect the results. In the GUI, the reactions can be moved up or down to set the order. This property can be defined using the XML tag <order>.
Materials, along with the volumetric ratios of the materials being formed or used, can be defined as reactants and products. The volumetric ratios are read as doubles. The main reactant should be assigned a ratio of 1.0, and the other reactants are assigned ratios that can be calculated from the stoichiometry and the base density of the material (see section 2.3). These properties are defined using the tags <reactant> or <product> and <materialName> and <ratio>.
If a reaction is set as discrete, the reaction rate is calculated individually for each particle. Also, any change in amount in the materials present in this particle, due to the reaction of this particle, is carried out from the came particle. In order for a reaction to be discrete, it should contain at least one non-universal reactant.
If this parameter is set to false, the rate of calculation is calculated for the entire system and then the reactant and the product materials are distributed between particles according to the plugins defined. This property can be defined using the XML tag <discrete>.
Other reactions can be added as successors to this reaction. When a reaction is deactivated by a trigger, its successor reaction is activated. The triggers of the successor reactions still have to keep them activated
The following XML block shows the setup of a reaction the XML input file.
<reaction name="myReaction">
<order>0</order>
<reactant>
<materialName>myMainReactantMaterial</materialName>
<ratio>1.0</ratio>
</reactant>
<reactant>
<materialName>mySecondReactantMaterial</materialName>
<ratio>0.5677</ratio>
</reactant>
<product>
<materialName>myMainProductMaterial</materialName>
<ratio>0.596</ratio>
</product>
<product>
<materialName>mySecondProductMaterial</materialName>
<ratio>1.57</ratio>
</product>
<discrete>true</discrete>
</reaction>
The name of the reaction can be given with the attribute name. The order defines the position of this reaction in the list of all reactions. All the reactants and products can be listed using the tags reactant and product respectively. The name of the material for the reactant of the product can be given between the tag materialName and the volumetric ratio of the reactant or the product can be given between the tag ratio. The value of the ratio is read as a double.
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 1.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 1.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 1.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 1.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.