.. -*- coding: utf-8 -*-
.. :Project:   SoL
.. :Created:   mer 25 dic 2013 11:16:58 CET
.. :Author:    Lele Gaifax <lele@metapensiero.it>
.. :License:   GNU General Public License version 3 or later
.. :Copyright: © 2013-2016, 2018-2024 Lele Gaifax
..

.. _tourneys management:

Tourneys management
-------------------

.. index::
   pair: Management; Clubs

The *tourney* is clearly the primary element of the whole system, everything has been designed
to allow an easy and fast management of these events.

The tourneys window by default does **not** show *future* tournaments: to see them, :ref:`reset
the filter <filtering>` applied to the :guilabel:`date` field.

.. contents::


Menu actions
~~~~~~~~~~~~

In addition to the :ref:`standard actions <standard actions>` the menu at the top contains the
following items:

.. figure:: tourneys.png
   :figclass: float-right

   Tourneys management

:guilabel:`Details`
  Opens the :ref:`management <tourney management>` window of the selected tourney.

:guilabel:`Competitors`
  Opens the :ref:`competitors fixup` window that allows the correction of the competitors of
  old tourneys.

:guilabel:`Replay again`
  Allows *duplicating* an existing tourney, expecially handy on teams events: it basically
  clones a tourney on the current date, with all its competitors; just be sure to update the
  description, maybe adjusting the date of the event!

:guilabel:`Assign`
  Change the ownership of the selected tourneys: you can select one or more tourneys
  keeping pressed the :kbd:`Ctrl` key and extend the selection with the :kbd:`Shift` key.

.. _tourneys other actions:

Other actions
+++++++++++++

The popup menu that appears by right clicking on a record of the table contains these further
actions:

:guilabel:`Download`
  Downloads an archive of the selected tourney's data.

:guilabel:`Lit page`
  Opens the corresponding ``Lit`` page in a different tab of the browser.

:guilabel:`Board labels`
  Print the labels to attach to the Carrom tables, with the QRCode that will allow
  self-insertion of the boards results of a match.

:guilabel:`Playbill`
  Print a simple playbill for the tourney, with the QRCode that will allow to reach
  its ``Lit`` page.

:guilabel:`Create knockout tourney`
  Create a new knockout tourney from a previous tournament, played with the *Swiss* system
  **and** *prized*: SoL asks how many competitors shall be copied into the new tournament,
  following the final ranking and setting their :ref:`seed position <competitors position>`
  consequently. The number must be a power of two (i.e. 2, 4, 8, 16...) and obviously less than
  or equal to the number of competitors in the source tournament.

.. _tourney insert and edit:

Insert and edit
~~~~~~~~~~~~~~~

.. index::
   pair: Insert and edit; Tourney

Date and description
++++++++++++++++++++

Each tourney has a :guilabel:`date` and a :guilabel:`description` of the event and there cannot
be two dictinct tourneys in the same date associated to a single championship.

Championship
++++++++++++

A tournament belongs to a particular :guilabel:`championship`. The lookup lets you choose one
among the currently active (i.e. **not** :ref:`closed <closed championship>`) championships
**and** at least one the following holds:

a. you are the owner (thus possibly created by you)
b. are linked to the clubs owned by you *or* or that you have been :ref:`associated <club-users
   association management>` with

Hosted by
+++++++++

It may happen that a tournament is hosted by a club other than the one that organizes the
championship: in these cases you can select the host club, which will appear on some printouts.

Location
++++++++

The :guilabel:`location` is optional and is purely descriptive.

Social site
+++++++++++

The optional URL of the *channel* dedicated to the tournament, usually in the context of
:ref:`solitaire tourneys championships <training championship>`, where every player records a
video of his games and eventually uploads it on the channel.

Duration and prealarm
+++++++++++++++++++++

The :guilabel:`duration` and :guilabel:`prealarm` refer to the length of a single round, and
are expressed in *minutes*. They will be used by the :ref:`countdown window <countdown>`.

When :guilabel:`duration` is set to 0 (zero), then no countdown will be shown.

.. _tourney rating:

Rating
++++++

A tourney may use a particular :guilabel:`rating`: in such a case, the first round is generated
accordingly with the rate of each player instead of using a random order.

It may be set it also on the :ref:`championship <championship rating>`, so that it will be
automatically initialized when you create a new associated tournament.

.. _tourney system:

System
++++++

The :guilabel:`system` selects the type of the tournament:

`Swiss`__
  each competitor meets the very same number of opponents, selected by the system from those at
  the same strength level, on average

`Knockout`__
  also known as *single-elimination tournament*, a competitor keeps playing until she lose a
  match, at which point he drops out

`Round-robin`__
  each competitor meets every other opponents: if there are 16 competitors, there will be 15
  rounds for a total of 120 matches

.. note:: For the `Knockout` tournaments consider the following points:

          * although SoL currently does not enforce any constraint in the number of
            competitors, to work correctly that must be a `power of two`__, that is 4, 8, 16,
            32, 64...

          * while they may use a particular `rating`, the rating will **not** be updated back
            with the event's matches

__ https://en.wikipedia.org/wiki/Swiss-system_tournament
__ https://en.wikipedia.org/wiki/Single-elimination_tournament
__ https://en.wikipedia.org/wiki/Round-robin_tournament
__ https://en.wikipedia.org/wiki/Power_of_two

.. _pairings:

Pairings
++++++++

The :guilabel:`pairing method` determines how the pairing are done at each new round:

``All possible matches``
  the ``all`` algorithm generates all possible combinations, without a particular ordering;
  this is meant to be used in **very particular cases**:

  * in the context of :ref:`solitaire tourneys championships <training championship>`, when you
    desire to generate *all* the rounds at once, not one at a time as usual

  * given that, unlike all the others algorithms, this may generate *incomplete* rounds with
    fewer matches than usual, it may be used as a fallback method in corner cases when other
    methods refuse to generate remaining matches: this may happen for example when you add new
    competitors to an already going tournament (yes, SoL :ref:`allows that <passersby>`)

``Ranking order``
  the ``serial`` algorithm will try to pair a competitor with one of the competitors that
  follow him in the current ranking order, for example the first with the second, the third
  with the fourth, and so on;

``Cross ranking order``
  to delay as much as possible most exciting matches, the ``dazed`` method is more elaborated:
  it considers the *groups* of competitors with the same points, and tries to pair the first
  with the one in the middle of the group, the second with the middle plus one, and so on;

  .. note:: After the first round, when the number of competitors with same points is *odd* and
            there are further competitors the algorithm adjusts the group to make it *even* by
            promoting the first competitor of the succeeding group (and thus with *less*
            points) as belonging to the former group.

  .. attention:: With less than eight competitors the ``serial`` and ``dazed`` algorithms cannot
                 guarantee the generation of all possible matches. Should this happen, SoL will
                 suggests to switch to the ``all`` method to generate remaining matches.

                 In general, with such a low number of competitors, I recommend using the ``all``
                 method from the beginning, or even better the ``Round-robin`` system.

``Staggered ranking order``
  the ``staggered`` method is equivalent to the previous when the number of competitors with
  the same points does not exceed 50, beyond which instead of pairing the first with the one in
  the middle of the serie a maximum offset of 25 is used regardless of the number: so you will
  get the first with the twenty-sixth, the second with the twenty-seventh and so on;

``Standard seeding [KO and RR]``
  the ``seeds`` method is the most commonly used in `knockout tourneys`__ and in
  `round-robin`__: it does *not use the current ranking*, but only the :ref:`positions
  <competitors position>` of the competitors or their :ref:`rate <players rates>`, usually
  determined by previous tournaments; SoL will raise an error when the tourney is not
  associated to a rating *nor* the position of all the competitors is specified; the first turn
  is generated pairing the first competitor against the last, the second against the
  second-last and so on;

``Circle [RR]``
  the `circle`__ method is a slightly different variant commonly used in `round-robin`
  tournaments.

__ https://en.wikipedia.org/wiki/Single-elimination_tournament#Seeding
__ https://en.wikipedia.org/wiki/Round-robin_tournament
__ https://en.wikipedia.org/wiki/Round-robin_tournament#Circle_method

Delay top players pairing
+++++++++++++++++++++++++

The :guilabel:`delay top players pairing`, meaningful only when the tourney is associated with
a rating, determines how many rounds will use an higher priority for the Glicko rate of each
competitor over the *net score* in the ordering used by the pairing method.

.. note::

   SoL uses five parameters to rank the competitors:

   1. points
   2. bucholz
   3. net score
   4. total score
   5. Glicko rate

   Before playing the first round the first 4 values are all zero, so only the fifth
   is crucial. At the beginning of the second round, all winners have the same score and
   the same bucholz, thus the net score become decisive.

   From the point of view of rounds generation, for the beauty of the game it is
   generally desirable to delay as much as possible the matches between *top players*: to
   this end it is sufficient to give an higher priority to the Glicko rate, moving it to
   the third place, after the bucholz and before the net score.

   The value assigned to this field controls how many turns shall be generated using this
   different sorting criteria: the default value of ``1`` means that it will be used at
   the end of the first round to generate the second one; a value of ``0`` instead
   inhibits this delay and therefore only the first round is determined by the Glicko
   rate, from the second onward it becomes irrelevant. Values higher than ``1`` have an
   impact less and less significant, because from the third round on the points and the
   bucholz become more and more predominant.

Delay compatriots pairing
+++++++++++++++++++++++++

The :guilabel:`delay compatriots pairing` tells for how many rounds the pairing-generator
algorithm should try to postpone matches between players *with the same points* belonging to
the same nation.

For example if the field is higher than 0 **and** the pairing method is not *"all possible
matches"*, when according to the current ranking there were 10 players with equal points and
the top three are Italian and the remaining of a different nationality, instead of trying to
pair the first with second or the first with the third, the system will try to couple the first
with the fourth and then with the fifth, considering the second and the third only if
necessary.

Phantom score
+++++++++++++

The :guilabel:`phantom score` is the score assigned to a player in the matches against the
*phantom player*, when there are an odd number of competitors. By convention these matches
assign a score of 25 to the player but there may be cases where a different score is more
appropriate, for example when the number of competitors is very low and winning 25—0 would be
an unfair advantage.

Owner
+++++

The user who is *responsible* of the tourney data, usually the one that inserted that
particular record: the information related to the tournament are changeable only by him (and
also by the *administrator* of the system).

.. _finals field:

Finals
++++++

The :guilabel:`finals` is the number of finals that will be played. It can be either left blank
or it must be a number between ``0`` and ``2`` inclusive: in the former case, finals will be
handled *manually*, that is SoL won't generate final matches but the results shall be reflected
by adjusting the bounties. A value of ``0`` means that there won't be any final, ``1`` means
that SoL will generate one single final match for the first and the second place, with ``2``
SoL will generate two final matches, one for the first and second place and another for the
third and fourth place.

Final kind
++++++++++

The :guilabel:`final kind` determines the kind of finals that will be played:

``Single match``
  the ``single`` kind will create one single round, with a match between the first and the
  second ranked competitors and, if :guilabel:`finals` is set to ``2``, another one pairing the
  third and the fourth ranked competitors

``Best of three games``
  the ``bestof3`` method will create at most three rounds, the final is won by the competitor
  that wins at least two of them.

As soon as the final scores of all these rounds are entered the *bounty giving* operation to
assign final bounties is performed automatically.

.. _drop-outs:

Drop outs
+++++++++

The :guilabel:`drop outs` allows you to choose a different mechanism to compute the ``bucholz``
value when there are `withdrawn` competitors. Normally that value is computed summing up the
``points`` of the opponents a given contender met, so that it's basically a *measure* of their
strength. When one (or more) of these opponents stop playing, their points value remains
constant and thus it does not contribute to the rank of the competitors he played against. In
highly competitive tournaments this may be seen as a *penalty*, so we tried to come up with a
mechanism to mitigate the effect. The options are:

``none``
  the classic behavior, no adjustment at all: the ``bucholz`` value is just the sum of the
  ``points`` of the opponents

``trend``
  computes the *average points* (excluding matches against the *phantom*) of the withdrawn
  player and assigns an *extra bonus* to his opponents, so that their ``bucholz`` value is
  *artificially augmented* by an amount equals to that average multiplied by the number of
  turns; in other words, it would appear *as if* the retired player kept going on at the same
  pace

``trend70``
  similar to the above, but it considers the 70% of the average points

  .. warning:: This is an **experimental** approach, be sure to understand the implications
               before using it!

.. toctree::
   :maxdepth: 2

   tourney
   competitors
