.. _flecks:

Composite Powder Material Simulation
====================================

.. include:: ../shared.rst

Introduction
------------

To simulate composite material, small filler particles are represented as material points with distinct coordinates, velocities, and temperatures.
Each particle, referred to as a "fleck" has its own radius. 
The following forces act on the flecks:

 * Gravity force
 * Drag force :math:`\pmb{F}_D = -6\pi \mu R (\pmb{v}-\pmb{u})`, where :math:`R` is the radius of the fleck, :math:`\mu` is the dynamic viscosity of the surrounding fluid or gas, 
   :math:`\pmb{v}` is the fleck's current velocity, and :math:`\pmb{u}` is the fluid or gas velocity. Currently, the gas velocity is set to 0.

Initial position of the filler particles
----------------------------------------

|kissam| requires a text file with the initial coordinates of the flecks in the following format: four columns containing the coordinates of the sphere's position and its radius (in micrometers).
The user can provide any filler particle configuration by generating files in this format by hand or by external scripts. 

To generate one of the typical filler configurations for the initial flecks file, the script ``flecks_on_powder.py`` provided in the |kissam| package can be used. 
The script puts the filler particles onto the surface of the metal powder particles. 

This script has the following format:

.. code:: bash

  ./flecks_on_powder.py [--config CONFIG] spheres_filename

Here, ``CONFIG`` is a JSON input file that must contain the fields ``Powder.FillerPSD`` and ``Powder.FillerVolumeFrac``. 
The ``spheres_filename`` is a text file :file:`spheres.dat` containing the initial coordinates and radii of the powder. 
The script outputs the coordinates and radii of the flecks, which are uniformly and randomly distributed around the powder particles. 
Below is an example of the script usage:

.. code:: bash

  ./flecks_on_powder.py --config input.json spheres.dat > flecks.dat

The field ``Powder.FillerPSD`` should be an array of pairs of numbers representing fleck sizes (percentiles and diameters in meters). 
The values must be cumulative by mass, with the first and last percentiles being 0 and 100, respectively (default is ``[[0,5e-6], [100,5.001e-6]]``). 
The ``Powder.FillerVolumeFrac`` field controls the total number of generated flecks and specifies the flecks' volumetric fraction in percent (default is ``5``).

Filler Material Settings
------------------------

The ``Powder.FlecksFile`` field specifies the use of a flecks filler text file. 
The default value is ``null``, indicating that no flecks model will be used.

The material of the filler is specified by the field ``Filler``. 
The default value is ``null``, but users can set any name, for example, ``"MyMaterialName"``. 
In this case, the section ``MaterialsLibrary.MyMaterialName`` must exist and contain the following parameters:

 * ``MaterialsLibrary.MyMaterialName.density``: Density of the filler in kg/m³.

 * ``MaterialsLibrary.MyMaterialName.Tmelting``: Filler melting temperature in K.

 * ``MaterialsLibrary.MyMaterialName.HeatCapacityVolumetric``: Filler average volumetric heat capacity in J/(m³･K).

The name ``MaterialsLibrary.ZrN`` already exists in the default JSON file.

.. code:: json
 
  "Filler": "ZrN",
  ...
  "MaterialsLibrary": {
    "ZrN": {
      "density"  : 7000.0,
      "Tmelting" : 3253.0,
      "HeatCapacityVolumetric" : 3.714e6
    }
  ...
  }



Parameters Overview
-------------------

The parameters in the :ref:`JSON file` that are used in the filler particle transport simulation are:

  In the ``Powder`` section:

    * ``Powder.FillerPSD``, ``Powder.FillerVolumeFrac`` --- these two fields are used in the ``flecks_on_powder.py`` script to generate the file for initial filler particle positions;

    * ``Powder.FlecksFile`` --- the file for initial filler particle position is specified in this field.

  In the data root:

    * ``Filler`` --- the name of the material for the filler.

  In the Materials library, a filler material need to have these fields:

    * ``MaterialsLibrary.MyMaterialName.density``: Density of the filler in kg/m³.

    * ``MaterialsLibrary.MyMaterialName.Tmelting``: Filler melting temperature in K.

    * ``MaterialsLibrary.MyMaterialName.HeatCapacityVolumetric``: Filler average volumetric heat capacity in J/(m³･K).


Results
-------

During the simulation, a directory named :file:`flecks` will be created in the output directory. 
Every ``config.DumpDataRate`` time steps, a file containing the flecks' characteristics will be generated. 
In the text file :file:`flecks/f-it000100000.dat`, each fleck's coordinate, radius, velocity, current temperature, and a  ``Trapped`` flag will be listed.

A negative fleck temperature indicates that the fleck is fully melted and no longer exists. 
The ``Trapped`` flag indicates the position of the fleck: ``Yes`` if the fleck is trapped in solid material that has not remelted during the current simulation, ``Yes,Remelted`` if the fleck is trapped in solid material that has remelted during the current simulation, and ``None`` if the fleck is in the gas.