.. _CreateParticles:

Particles Creation Model
========================

This model allows the creation of test particles during a running simulation. The model can be enabled with the :literal:`Create Particles file name` parameter 
in the :ref:`param.dat<ParamFile>` file. If a file name is specified here, then the model is activated.

| It is only available for test particles.
| All particle creation events are reported in the Fragments file :ref:`FragmentsFile`.

The maximum number of particles in a simulation is the number of initial particles and test particles plus the value set in :literal:`Nfragments`.

.. math::

	N_{Maximum} = N{(Initial bodies)} + N{(Initial test particles)} + Nfragments

If the maximum number of allowed particles is reached, then no more new particles are created until some other particles are removed from the simulation by
a collision or ejection event. 

The following parameters are relevant for the particle creation model and can be set in the :ref:`param.dat<ParamFile>` file:

- :literal:`Create Particles file name`, enable small bodies collisions model.
- :literal:`Nfragments`,  Number of additional memory size for debris particles, in particle numbers, (default 0).


The first line in the 'Create Particles file' contains the particle creation mode:

- | :literal:`Create Particles mode`:

   - 1: particles are generated by specified ranges in Kepler elements.
   - 2: particles are generated as escaping particles from specified parent bodies.

Particles Creation Mode 1
-------------------------
Enabled with :literal:`Create Particles mode = 1`.

The coordinates of the new generated particles are set by drawing uniform random numbers in a range of Kepler elements.

The particle creation file contains the following parameters:

- Create Particles mode = 1
- Maximum number of particles: Includes all particles, if this number is reached, then no new particles are generated
- Creation rate: in years, this specifies how frequent particles are generated.
- a: mean value of semi-major axis, in AU
- da: width of semi-major axis range, in AU
- e: mean value of eccentricity
- de: width of eccentricity range
- inc: mean value of inclination, in radians
- dinc: width of inclination range, in radians
- m: mass, in Solar Masses
- r: physical radius, in AU

The additional Keplerian elements (:math:`\Omega`, :math:`\omega` and :math:`M`) are generated between :math:`0` and :math:`2\pi`.

Example::

	Create Particles mode = 1
	Maximum number of particles = 100
	Creation rate = 50.0
	a = 5.2
	da = 4.0
	e = 0.8
	de = 0.05
	inc = 0.05
	dinc = 0.05
	m = 0.0
	r = 1.0e-10


Particles Creation Mode 2
-------------------------
Enabled with :literal:`Create Particles mode = 2`.

The coordinates of the new generated particles are generated as escaping particles from parent bodies. A list of parent bodies
can be specified in the file. New generated particles are placed 3 times the physical radius of the parent body away from its center. 
The direction is chosen isotropic and randomly. The escaping velocity is chosen randomly between the range Vmin and Vamx.
Where Vmin and Vmax are given in terms of the escape velocity of the parent body. 

For example: Vmin = 1 and Vmax = 2, then the escaping velocity of the new particle between 1 and 2 times :math:`v_{esc} = \sqrt{2GM/d}`,
where :math:`d = 3 R`, :math:`M` and :math:`R` are the mass and radius of the parent body.

The particle creation file contains the following parameters:

- Create Particles mode = 2
- Maximum number of particles: Includes all particles, if this number is reached, then no new particles are generated
- Creation rate: in years, this specifies how frequent particles are generated.
- Vmin, minimum velocity, in terms of the escape velocity of the parent body.
- Vmax, maximum velocity, in terms of the escape velocity of the parent body.
- m: mass, in Solar Masses
- r: physical radius, in AU
- List of particle indizes: In the following, the indizes of the parent bodies must be listed.

Example::

	Create Particles mode = 2
	Maximum number of particles = 100
	Creation rate = 50.0
	Vmin = 1.0
	Vmax = 1.0
	m = 0.0
	r = 1.0e-10
	List of particle indizes:
	4
	8
	12