Taiko Ranking philosophy
Here are a few main objectives or hypothesis used in this project:

1. Mods should affect the difficulty for what they actually modify. If beatmap A is the emulation of beatmap B with HR, then every score on beatmap A is worth a much as the same score on beatmap B with HR. This is true for every mod.
2. A player will miss or play as good hits the hardest objects first. This means that when choosing which objects did the player miss or play as good hits, the hardest objects are chosen.
3. Good hits and misses affect close objects. This is to reward more a perfect score compared to a score containing the first one but with misses on additional objects.
4. An object difficulty is only determined by the objects before it, except for the part due to close good hits and misses.

Main idea
Here is how the star-rating of a score is computed:

1. A difficulty is computed for all objects assuming the score is a perfect (SS).
2. Hardest objects are marked as misses or good hits.
3. All objects difficulties are computed again, this time with misses and good hits.
4. The score is given a star-rating by doing a weighted sum of the objects difficulties. Hard objects are weighted more.

The drawback of this method is that it takes longer to compute the star-rating of a score. The current ppv2 system is much faster because performances points are deduced from the beatmap star-rating. But, the advantage of this method is that it is more accurate. A few misses on a beatmap composed of long easy parts and one short hard part will decrease a lot the star-rating. While a few misses on a beatmap composed of only hard parts will less affect the star-rating.

An even more accurate method would be to compute again each object difficulties for each good hits or misses, but this one gets very slow on bad scores and long beatmaps.

An object difficulty is based on four main skills:

1. Density: how close one object is to other objects.
2. Reading: how hard it is to read the object, not to be confused with pattern.
3. Pattern: how the object is inside an unusual pattern.
4. Accuracy: how hard it is to play accurately the objects.

Density
Density represents how objects are close to others. Here is the process to compute object densities:

1. First, all offsets are modified according to the time window allowed. Small gaps are increased, while large gaps are decreased. This does not change the beatmap density a lot, but I believe it still is important. Sometimes, streams are just easier if you start them slightly before and end them slightly after. Those slight changes get smaller as the time window gets smaller.
2. Then, two types of densities are computed for each object: one key density and one hands density.
   
   1. Key density, only takes into account the objects you play with the same key of your keyboard. In order not to give an advantage to any playstyle, I assumed there are four independent fingers: two dons and two kats. Each don, respectively kat, finger is alternating with the other don, respectively kat, finger.
   2. Hands density, takes into account all previous objects.
   Those two density types help lowering the object difficulty when a small number of objects are very close, while still rewarding long streams with lots of color changes.

Reading
Reading shows how hard it is to read an object. This is determined by three variables:

1. Time.
2. The visible surface of the object at a given time. For example: if the object is hidden by another object, like a 1/8 stream with regular speed, or simply the object not being visible due to FL or HD.
3. How interesting it is to see the object at a given time. Seeing the object a dozen of milliseconds or one hour before it is played is not really useful.

The interest value is very important as this is what shows that slow objects are easier with FL or fast objects easier with HD. This also rewards HD on slow objects and HR on fast objects.

Pattern
Pattern difficulty is not simple to compute. Everyone can have a different approach for each pattern. In order not to advantage anyone, I assumed a pattern difficulty was linked to how many times it was seen among previous objects and how far are those occurrences. This helps identifying dddddddd or ddkddkddk as easy patterns. This also shows that the last object in kdkdkdkdkdkdd is harder because it uses a different pattern.
Sadly, this method was not enough because ddddkkkk streams were heavily rewarded compared to ddkdkkdk streams. To compensate this issue, objects following a mono-color pattern are marked as easier. While this fixes the problem in some way, I believe it is not the best solution.

Accuracy
Accuracy is divided in three sub-skills defining why an object is hard to play accurately:

1. Time window: if the time window of an object is smaller then it will be harder. Time window is linked to the beatmap overall difficulty (OD) and the mods used.
2. Rhythm change: if the spacing between objects always changes then it gets harder to play them correctly. A similar approach to patterns is used, the time elapsed before the current object is searched among the previous objects. The more it is found, the smaller the rhythm change difficulty.
3. Very slow speed: this aims to show that it is hard to guess on which beat is a very slow object.

First, the project has two branches: master and cassage_wip. Switch to cassage_wip to have the latest modifications.
The following list shows you where to search what, I have included only the most important parts.

1. Main structures: map.h object.h
2. Common: treatment.c
3. Density: density.c
   Density is not too complicated to understand but the offset optimization with time windows is a little tricky.
   
4. Reading: reading.c mesh.c gts_mesh.c
   Reading is not simple to understand. The program builds a 3D mesh based on time, interest and the object visible width. The reading rating is then deduced from the mesh volume.
   
5. Pattern: pattern.c
   Pattern shouldn't be too hard but it might be long to read.
   
6. Accuracy: accuracy.c spacing_counter.c
   Accuracy is quite simple to read.
   
7. Combining the four skills: final_star.c
8. Good hits and misses handling: convergor.c replay.c score.c

Most functions used to transform numbers to other numbers are stored as piecewise linear functions in the config file. This is not as good as a power function or a more complex polynomial function, but it is easy to modify while still knowing how the function behaves.

The config file is written in yaml. Most values have a few explanations on what they modify. Here is an example on how to modify it:

Original config:
Those are the values for a piecewise linear function.

...
  ### Hit_window smallness
  ## Brief:
  # Give some difficulty to object based on its hit window.
  ## Variable:
  # x is in ms, the hit window size
  # y is a difficulty multiplier
  # Notes:
  #             Great Good
  # od10 + DT = 12    32
  # od10      = 18    48
  # od7       = 27    66
  # od6       = 30    72
  # od5       = 33    78
  # od1       = 45    102
  # od1  + HT = 60    136
  hit_window_smallness:
  - [ 0.0,       2.5 ]
  - [ 12.0,      2.5 ]
  - [ 27.0,      1.5 ]
  - [ 33.0,      1.2 ]
  - [ 60.0,      1.05 ]
  - [ 140.0,     1.0 ]
  - [ 3600000.0, 1.0 ]
...

A modification:
Rewards even more small hit windows.

...
  hit_window_smallness:
  - [ 0.0,       4.0 ]
  - [ 12.0,      4.0 ]
  - [ 27.0,      3.0 ]
  - [ 33.0,      1.2 ]
  - [ 60.0,      1.05 ]
  - [ 140.0,     1.0 ]
  - [ 3600000.0, 1.0 ]
...

By editing the values too much, you might get "Error: Out of bounds value ('x') for linear_func ('y')". This means the input value x didn't match the possible values in the linear function y.