vice.multizone.from_output
==========================

Obtain an instance of the ``multizone`` class given either the path
to an output of a ``multioutput`` object itself.

**Signature**: vice.multizone.from_output(arg)

.. versionadded:: 1.2.0

Parameters
----------
arg : ``str`` or ``multioutput``
	The full or relative path to the output directory; the '.vice'
	extension is not necessary. Alternatively, an output object.

Returns
-------
mz : ``multizone``
	A ``multizone`` object with the same parameters as the one which
	produced the output.

	.. note::

		``multizone`` simulations by default save a copy of their
		attributes with their output, a feature which makes this
		function possible. If the user calls the ``run`` function with
		the keyword argument ``pickle = False``, the necessary files
		to reconstruct the simulation will not be produced. In this
		case, this function will return a ``multizone`` object with
		the default parameters.

Raises
------
* TypeError
	- ``arg`` is neither a ``multioutput`` object nor a string.
* IOError [Only occurs if the output has been altered]
	- The output is missing files
* UserWarning
	- Attributes were not saved with the output at user's request, and
	  the default ``multizone`` object will be returned.

Notes
-----
.. note::

	If arg is either a ``singlezone`` output or an ``output`` object,
	a ``singlezone`` object will be returned.

.. note::

	This function serving as the reader, the writer is the
	vice.core.multizone._multizone.c_multizone.pickle function,
	implemented in Cython_.

	.. _Cython: https://cython.org/

Example Code
------------
>>> import numpy as np
>>> import vice
>>> vice.multizone(name = "example", n_zones = 3)
>>> mz.run(np.linspace(0, 10, 1001))
>>> mz = vice.multizone.from_output("example")
>>> mz
	vice.multizone{
		name -----------> example
		n_zones --------> 3
		n_stars --------> 1
		verbose --------> False
		simple ---------> False
		zones ----------> ['zone0', 'zone1', 'zone2']
		migration ------> Stars: <function _DEFAULT_STELLAR_MIGRATION_ at 0x111393f80>
						  ISM:     MigrationMatrix{
			0 ---------> {0.0, 0.0, 0.0}
			1 ---------> {0.0, 0.0, 0.0}
			2 ---------> {0.0, 0.0, 0.0}
		}
	}