Add PI extraction calculation (#107)

* Add: new PI extraction calculation documentation and implementation in C# and Python

* Fix: correct a typo in the README regarding language definition for new snippets

* Add: enhance PI extraction calculation documentation and include it in the navigation

* Fix: formatting for pi-extraction.cs

* Chore: refactor pi-extraction.py

---------

Co-authored-by: Steven Noorbergen <91969936+steven-noorbergen@users.noreply.github.com>

README.md

@@ -131,7 +131,7 @@ There are various places where we insert code snippets into the documentation to
 
 Snippets are placed in the `snippets` folder, grouped in subfolders by topic. Each snippet is a separate file per language (based off of its extension), with a central (autogenerated) `.md` file that includes the snippets for each language. If you want to add a new language to a snippet, create the new file, and the build pipeline will automatically include it in the final documentation.
 
-If you are adding the first snippet for a new language, it will need to be defined in `scripts/generate-snippets.py`, so that the build pipeline knows to include the file extension when searching for snippets, and what langauge to use for syntax highlighting.
+If you are adding the first snippet for a new language, it will need to be defined in `scripts/generate-snippets.py`, so that the build pipeline knows to include the file extension when searching for snippets, and what language to use for syntax highlighting.
 
 When adding new snippets, write it in any supported/configured language, and include it as follows:
 

docs/guides/pi.md

@@ -0,0 +1,7 @@
+# PI
+
+## Extraction calculation
+To calculate the amount extracted from the ESI PI endpoint is more complex then just pulling from the ESI and using the values, snippets below walk through calculating each stage with its variations.
+<h3>Example</h3>
+
+--8<-- "snippets/formulae/pi-extraction.md"

mkdocs.yml

@@ -21,6 +21,7 @@ nav:
     - "Single-Sign-On": services/sso/index.md
   - Guides and Examples:
     - Useful Formulae: guides/useful-formulae.md
+    - PI: guides/pi.md
   - Community: community/community-services.md
 not_in_nav: |
   community/*/index.md

scripts/generate-snippets.py

@@ -11,12 +11,14 @@
 # The name will be used in the generated markdown file.
 EXTENSION_MAPPING = {
     ".py": "Python",
+    ".cs": "C#",
 }
 
 # The mapping of file extensions to syntax highlighting names. The key is the file
 # extension (including the dot), and the value is the syntax highlighting name.
 SYNTAX_MAPPING = {
     ".py": "python",
+    ".cs": "csharp",
 }
 
 # The file extension for the combined markdown file.

snippets/formulae/pi-extraction.cs

@@ -0,0 +1,32 @@
+int[] CalculateExtractorValues() {
+
+    //Inputs - these are set from the API results.
+    //Note that all times are in seconds.
+    int duration = 171000; //1d 23h 30m; from API expiryTime-installTime
+    int cycleTime = 30 * 60; //30 minutes, value from API cycleTime * 60
+    int quantityPerCycle = 6965;
+
+    //These constants are the defaults in dgmAttributeTypes. They may change.   
+    const float decayFactor = 0.012f; //Dogma attribute 1683 for this pin typeID
+    const float noiseFactor = 0.8f;   //Dogma attribute 1687 for this pin typeID
+
+    int numIterations = duration / cycleTime;
+    float barWidth = cycleTime / 900f;
+    int[] values = new int[numIterations];
+
+    for (int i = 0; i < numIterations; i++) {
+        float t = (i + 0.5f)*barWidth;
+        float decayValue = quantityPerCycle/(1 + t * decayFactor);
+        double phaseShift = Math.Pow(quantityPerCycle, 0.7f);
+
+        double sinA = Math.Cos(phaseShift + t * (1/12f));
+        double sinB = Math.Cos(phaseShift / 2 + t * 0.2f);
+        double sinC = Math.Cos(t * 0.5f);
+
+        double sinStuff = Math.Max((sinA + sinB + sinC) / 3, 0);
+
+        double barHeight = decayValue * (1 + noiseFactor * sinStuff);
+        values[i] = (int) (barWidth * barHeight);
+   }
+   return values;
+}

snippets/formulae/pi-extraction.py

@@ -0,0 +1,28 @@
+import math
+
+# These constants are the defaults in dgmAttributeTypes. They may change.
+decay_factor = 0.012  # Dogma attribute 1683 for this pin typeID
+noise_factor = 0.8  # Dogma attribute 1687 for this pin typeID
+
+def calculateExtractorValues(total_cycles = 30, cycle_time = 30 * 60, qty_per_cycle = 6965):
+    """
+    :param int total_cycles: End time in seconds - start time in seconds / cycle_time
+    :param int cycle_time: Cycle time, in seconds
+    :returns Generator[int]: A generaotr that iterates over all values
+    """
+    bar_width = float(cycle_time) / 900.0
+
+    for cycle in range(0, total_cycles):
+        t = (cycle + 0.5) * bar_width
+        decay_value = qty_per_cycle / (1 + t * decay_factor)
+        phase_shift = pow(qty_per_cycle, 0.7)
+
+        sin_a = math.cos(phase_shift + t * (1 / 12))
+        sin_b = math.cos(phase_shift / 2 + t * 0.2)
+        sin_c = math.cos(t * 0.5)
+
+        sin_stuff = max((sin_a + sin_b + sin_c) / 3, 0)
+
+        bar_height = decay_value * (1 + noise_factor * sin_stuff)
+
+        yield bar_width * bar_height