Poisson-approval

----------------------------------------------------------------

* Random initialization of iterated voting and fictitious play:

* Add the option ``'random_tau'``: a random tau-vector that is consistent with the voting rule.
* Add the option ``'random_tau_undominated'``: a random tau-vector where each voter randomly uses an undominated
ballot. Relies on the new method ``Profile.random_tau_undominated``.
* Remove the option ``'random_strategy'``: it had an unnatural behavior for Plurality and Anti-Plurality.
Subsequently, remove also the method ``Profile.random_strategy``.

* In iterated voting and fictitious play, winning frequencies are computed from t=1 instead of t=0. The motivation is
twofold. Firstly, if the result at initialization is essentially arbitrary and, for example, candidate `a` always
wins afterwards, we consider it more natural to have a winning frequency of 1 for `a`. Secondly, when using the
arithmetic average, the denominator is the number of steps, rather than the number of steps plus one. As a
consequence, we updated the helper functions in order to account for this time translation:

* Replace ``one_over_t_plus_one`` with ``one_over_t``.
* Replace ``one_over_sqrt_t_plus_one`` with ``one_over_sqrt_t``.
* Replace ``one_over_log_t_plus_two`` with ``one_over_log_t_plus_one``.
* Replace ``one_over_log_log_t_plus_fifteen`` with ``one_over_log_log_t_plus_fourteen``.

* Fix a rare bug: in some tau-vectors, when computing the trio event, an offset was found greater than 1, whereas theory
shows that it is lower than 1. This used to cause a collateral error when computing the best response with the
offset method.

---------------------------------

---------------------------------

* Implement *binary plots*, i.e. plots designed to study profiles based on two ranking with varying utilities. Cf. the
corresponding tutorial.

* Intensity heat maps.
* Candidate heat maps.
* Annotate the Condorcet regions.

* Utilities:

* Add ``d_candidate_ordinal_utility``: ordinal utility of a candidate for a given preference order.
* Add ``my_range``: similar to ``range``, but works also for fractions.
* Add ``my_sign``: sign of a number. Return an integer in {-1, 0, 1}, unlike ``np.sign``.

---------------------------------------------------

---------------------------------------------------

* Add new iterables and random factories for profiles, tau-vectors and strategies. These iterables and random factories
are very flexible: you can specify that some types have a fixed share, that only some types have a variable share,
etc. Cf. the corresponding tutorials and the corresponding section in Reference.
* Remove ``ExploreGridProfilesOrdinal`` and ``ExploreGridTaus``: their features are included in the new iterables.
* Remove all classes whose name began with ``Generator``: their features are included in the new random factories.
* All the methods that had a parameter ``generator`` now have a parameter ``factory`` instead. This choice is due to
the fact that the word "generator" has another meaning in Python, which could be misleading.
* ``SimplexToProfile`` works similarly to the new iterables and random factories. In particular it is now allowed to
use the same type several times, for example in the fixed shares and in the variable shares.
* There is a new syntax option to define a ``ProfileHistogram``, which is especially convenient for
iterables and random factories.
* Utilities:

* Add ``iterator_integers_fixed_sum``: iterate over vectors of integers with a fixed sum.
* Add ``iterate_simplex_grid``: iterate over the points in the simplex, with rational coordinates of a given
denominator.
* Add ``allowed_ballots``: allowed ballots in a voting rule.

* Complete revision of the tutorials.

-----------------------------------------

-----------------------------------------

* ``Profile`` and its subclasses, ``TauVector``, ``Asymptotic`` and its constructors (such as
``Asymptotic.poisson_value``, ``Asymptotic.poisson_eq``, etc.) accept an optional argument ``symbolic``. If False
(default), then all computations are numeric as before. If True, then almost all computations are symbolic; the
only exception is when the trio event can be evaluated only via the Dual Magnitude Theorem. Please note that:

* This feature relies on the external package `sympy` and works with its current version (1.5.1) but we cannot
guarantee that it will still work with future versions of `sympy`.
* When activated, it slows downs the computation considerably. In particular, it is strongly advised not to use
fictitious play or iterated voting in symbolic mode.

* Equality and closeness tests:

* ``Asymptotic.isclose`` is renamed to ``look_equal``: in numeric mode, it is still a closeness test, but in
symbolic mode, it is an equality test.
* Remove ``StrategyThreshold.isclose``: this method was not used anymore.

* ``Event`` and its subclasses take a ``TauVector`` as input, instead of the dictionary of its coefficients. Firstly, it
speeds up computation. Secondly, it avoids a minor bug in symbolic mode.

* Utilities:

* Add the classes ``ComputationEngine``, ``ComputationEngineNumeric`` and ``ComputationEngineSymbolic``, defining
how some mathematical operations are performed.
* Add the function ``computation_engine``: choose the computation engine.
* Remove the utility function ``barycenter`` and include it as a method in ``ComputationEngine``.

-------------------------------------

-------------------------------------

* ``StrategyThreshold``: for each ranking, there is a ``threshold`` (like before) and an optional ``ratio_optimistic``.
Voters whose utility for their second candidate is equal to the threshold of the strategy are split: a share
``ratio_optimistic`` behave as if the threshold was higher (in Approval, they vote only for their top candidate)
and the rest behave as if the threshold was lower (in Approval, they vote for their two first candidates). Hence the
strategy is mixed. Note that this only makes a difference when the profile has "atoms" (concentration of voters on a
single utility point); currently, this is only the case in ``ProfileDiscrete``.
* For ``ProfileDiscrete``, fictitious play and iterated voting consider that the responses use a ratio of optimistic
voters equal to 1/2.
* Add ``ProfileCardinalContinuous``: this abstract class is a child of ``ProfileCardinal`` and a parent class
of ``ProfileNoisyDiscrete`` and ``ProfileHistogram``. In these profiles, the ratios of optimistic voters are not
important because there is no "atom".
* ``GeneratorStrategyThresholdUniform``: for each ranking, the ratio of optimistic voters is also chosen uniformly.
* The utility ``DictPrintingInOrderIgnoringNone`` now also ignores values that are iterables containing only None.

-------------------------------------------

-------------------------------------------

* Nicer colors than before. For example, an equal mix of candidate `a` (red) and `b` (green) was brownish, whereas it
is now yellow. Similarly, a mix of the three candidates (red, green, blue) was gray, and it is now white. Etc.
* Improved ternary plot shortcuts ``ternary_plot_n_equilibria``, ``ternary_plot_winners_at_equilibrium`` and
``ternary_plot_winning_frequencies``:

* New versions of these functions with more options. Cf. the tutorial on ternary plots.
* Add class ``SimplexToProfile`` to map a point of the simplex to a profile. This includes the possibility of
having fixed additional voters.

* ``TernaryAxesSubplotPoisson``:

* Add methods ``legend_color_patches`` and ``legend_palette``: two different styles of legends for candidate
heat maps.
* The method ``heatmap_candidates`` has a new parameter ``legend_style``.
* The method ``annotate_condorcet`` has a new parameter ``d_order_fixed_share`` to account for fixed additional
voters.
* In several methods, the old parameters ``color_a``, ``color_b`` and ``color_c`` are suppressed, because
the colors for `a`, `b`, `c` are not modifiable anymore.

* Random strategies:

* Add ``GeneratorStrategyTwelveUniform``.
* Add method ``Profile.random_strategy``: return a random strategy that is suitable for the profile (e.g. an ordinal
strategy for an ordinal profile, etc.).
* ``ProfileCardinal.iterated_voting`` and ``ProfileCardinal.fictitious_play`` now accept the parameter
``init='random'`` for an initialization with a random strategy.

* Add ``Profile.order_and_label``: order and label of a discrete type. This auxiliary function is used for the ternary
plots.

----------------------------------------