Split a stash of states into two stashes depending on the specified options.

        The stash from_stash will be split into two stashes depending on the other options
        passed in. If to_stash is provided, the second stash will be written there.

        stash_splitter overrides stash_ranker, which in turn overrides state_ranker.
        If no functions are provided, the states are simply split according to the limit.

        The sort done with state_ranker is ascending.

        :param stash_splitter:  A function that should take a list of states and return a tuple
                                of two lists (the two resulting stashes).
        :param stash_ranker:    A function that should take a list of states and return a sorted
                                list of states. This list will then be split according to "limit".
        :param state_ranker:    An alternative to stash_splitter. States will be sorted with outputs
                                of this function, which are to be used as a key. The first "limit"
                                of them will be kept, the rest split off.
        :param limit:           For use with state_ranker. The number of states to keep. Default: 8
        :param from_stash:      The stash to split (default: 'active')
        :param to_stash:        The stash to write to (default: 'stashed')

        :returns:               The simulation manager, for chaining.
        :rtype:                 SimulationManager

def split(self, stash_splitter=None, stash_ranker=None, state_ranker=None,
              limit=8, from_stash='active', to_stash='stashed'):
        """
        Split a stash of states into two stashes depending on the specified options.

        The stash from_stash will be split into two stashes depending on the other options
        passed in. If to_stash is provided, the second stash will be written there.

        stash_splitter overrides stash_ranker, which in turn overrides state_ranker.
        If no functions are provided, the states are simply split according to the limit.

        The sort done with state_ranker is ascending.

        :param stash_splitter:  A function that should take a list of states and return a tuple
                                of two lists (the two resulting stashes).
        :param stash_ranker:    A function that should take a list of states and return a sorted
                                list of states. This list will then be split according to "limit".
        :param state_ranker:    An alternative to stash_splitter. States will be sorted with outputs
                                of this function, which are to be used as a key. The first "limit"
                                of them will be kept, the rest split off.
        :param limit:           For use with state_ranker. The number of states to keep. Default: 8
        :param from_stash:      The stash to split (default: 'active')
        :param to_stash:        The stash to write to (default: 'stashed')

        :returns:               The simulation manager, for chaining.
        :rtype:                 SimulationManager
        """
        states = self._fetch_states(stash=from_stash)

        if stash_splitter is not None:
            keep, split = stash_splitter(states)
        elif stash_ranker is not None:
            ranked_paths = stash_ranker(states)
            keep, split = ranked_paths[:limit], ranked_paths[limit:]
        elif state_ranker is not None:
            ranked_paths = sorted(states, key=state_ranker)
            keep, split = ranked_paths[:limit], ranked_paths[limit:]
        else:
            keep, split = states[:limit], states[limit:]

        keep, split = map(list, (keep, split))

        self._clear_states(from_stash)
        self._store_states(from_stash, keep)
        self._store_states(to_stash, split)
        return self