vice.migration.specs.stars
==========================

Type : <function>

Default : vice._globals._DEFAULT_STELLAR_MIGRATION_

.. note:: The default migration setting does not move stars between
	zones at all.

The stellar migration prescription.

This function must accept at ``int`` followed by two real numbers as
parameters, in that order. These are interpreted as the zone number in
which a star particle forms in a multizone simulation, the time at
which it forms in Gyr, and the time in the simulation in Gyr.

This function must return an ``int`` describing the zone number of the
star particle at times following its formation.

Notes
-----
The third parameter returned by this function is interpreted as the
time since the start of the simulation, **NOT** the age of the star
particle in question.

This function will never be called with a third parameter that is
smaller than the second parameter. These are times at which star
particles have not formed yet.

.. tip:: If users wish to write extra data for star particles to an
	output file, they should set up this attribute as an instance of
	a class. If this class has an attribute ``write``, VICE will switch
	it's value to ``True`` when setting up star particles for
	simulation. The lines which write to the output file can then be
	wrapped in an ``if self.write`` statement.

.. tip:: If a multizone simulation will form multiple star particles
	per zone per timestep, they can be assigned different zone
	occupation histories by allowing the function of initial zone
	number and formation time to take a keyword argument ``n``.
	VICE will then call this function with ``n = 0``, ``n = 1``,
	``n = 2``, and so on up to ``n = n_stars - 1``, where ``n_stars``
	is the number of star particles per zone per timestep.

Example Code
------------
>>> import vice
>>> example = vice.migration.specs(3)
>>> def f(zone, tform, time):
	# swap stars between zones 0 and 1 when they're >1 Gyr old
	if zone == 0:
		if time - tform > 1:
			return 1
		else:
			return 0
	elif zone == 1:
		if time - tform > 1:
			return 0
		else:
			return 1
	else:
		return zone
>>> example.stars = f