docs updated

docs/README.md

@@ -8,15 +8,15 @@ Calculator/Factory Planner for factory management games.
 # General usage
 
 Calculator can work in two modes: `Drag and Drop mode` and `Point and Click mode`.
-First can be used on PC only and will not work on touchscreen mobile devices.
-Second is optimized for mobile devices, but may be used also on PC.
-Modes may be switched on and off using `Options` dialog.
+First is optimized for PC usage and is turned on by default on PC.
+Second is optimized (and default) for mobile devices, but also may be used on PC.
+Modes are switched on and off using `Options` dialog.
 
 ## Drag and Drop mode
 
 In this mode everything is dragged by primary mouse button.
 Note: if both `Drag and Drop` and `Point and Click` modes are enabled,
-there will be delay between mouse button is pressed on item and dragging actually starts.
+there will be delay (300 ms) between mouse button is pressed on item and dragging actually starts.
 This is done to differentiate `Click` and `Drag` events.
 
 <details><summary>Drag factory and drop on blueprint</summary>
@@ -29,6 +29,11 @@ This is done to differentiate `Click` and `Drag` events.
 ![drag-n-drop-2](./assets/drag-n-drop-2.gif)
 </details>
 
+<details><summary>Drag link to change ports ordering</summary>
+
+![drag-n-drop-6](./assets/drag-n-drop-6.gif)
+</details>
+
 <details><summary>Drag to move factory</summary>
 
 ![drag-n-drop-3](./assets/drag-n-drop-3.gif)
@@ -58,6 +63,11 @@ In this mode items can be selected with click, and then pasted/moved with anothe
 ![point-n-click2](./assets/point-n-click2.gif)
 </details>
 
+<details><summary>Change port ordering (should click carefully on free space between ports)</summary>
+
+![point-n-click4](./assets/point-n-click4.gif)
+</details>
+
 <details><summary>Move factory</summary>
 
 ![point-n-click3](./assets/point-n-click3.gif)
@@ -82,6 +92,24 @@ Factory may be rotated to create more pretty looking links.
 ![rotation](./assets/rotation.gif)
 </details>
 
+# Factory count adjustment
+
+Factory count can be set using `hamburger` factory menu. Optionally `Plus` and `Minus` button on factory card face can be turned on in settings. `Plus` and `Minus` adjust count by one, while textbox on menu can be used to set fractional counts. There is also `Mass Update Count` toolbar button, which could be used to apply automatically calculated counts.
+
+<details><summary>See in action</summary>
+
+![count-adjustment](./assets/count-adjustment.gif)
+</details>
+
+# Factory upgrade / downgrade
+
+If factory has next or previous tier version, upgrade option becomes available inside `hamburger` factory menu. Turning upgrade mode affects all factories.
+
+<details><summary>See in action</summary>
+
+![upgrade-mode](./assets/upgrade-mode.gif)
+</details>
+
 # Inspection of logistic transport
 
 Logistic transport can be inspected for links, which connects items with known transport (conveyors, pipes, manipulators, robotic arms). When clicking on link menu, logistic info will be shown automatically. Specific transport may be locked, in this case locked transport will be preferred for entire blueprint.
@@ -93,7 +121,7 @@ Logistic transport can be inspected for links, which connects items with known t
 
 # Summary window
 
-Summary window will show overall consumption / production of blueprint. Because it is calculated while blueprint is updated - it is recommended to turn it off for very large blueprints. Summary window can work in two modes - simple and expanded. Modes are switched sequentially by corresponding button. Summary window will be empty if blueprint is empty or not calculated. Summary window shows production / consumption only for open ends (not connected to anything).
+Summary window will show overall consumption / production / building costs of blueprint. Because it is calculated while blueprint is updated - it is recommended to turn it off for very large blueprints. Summary window can work in two modes - simple and expanded. Modes are switched sequentially by corresponding button. Summary window will be empty if blueprint is empty or not calculated. Summary window shows production / consumption only for open ends (not connected to anything).
 
 
 <details><summary>See in action</summary>
@@ -135,6 +163,25 @@ Solving is done with fixed precision, which can be changed in `Settings`.
 The lower number means higher precision and better accuracy.
 Because of this, there will be computation errors if connected factories throughput greatly differs or precision is too low.
 
+## Automatic graph error detection
+
+Factory chains may be unbalanced when factory outputs two item types, and these items directly or through production chain will be both feed to another factory at different rate. Production cycles may also be unbalanced. In this case graph solver cannot solve factory io, so entire flow rate will be 0. This is expected, because real production chain of this type will also produce at zero rate after some time, because one output will be clogged or input will be starved.
+
+Graph solver has automatic error detection and will try to find port which causes error. This is implemented by adding virtual sink with lowest priority to each factory output. If this virtual sink flow is non-zero this means connected factory output is unbalanced, and such output will be highlighted in red color. To resolve this error, some building should be added instead of this virtual sink, which will consume overflown items.
+
+Only unbalanced outputs are detected automatically, because it is most common case.
+
+<details><summary>Example</summary>
+
+![unbalanced-graph](./assets/unbalanced-graph.gif)
+</details>
+
+## Special buildings
+
+Almost every game implementation has set of special buildings. These buildings are usually represented as containers (maybe inexistent in real game) which accept all items of some kind (fluid, solid, etc). These buildings have 3 recipes, input, output and input+output. They could be used as utility buildings to tune production flows or for nicer graph layouts.
+
+# Fine-tuning graph solve process
+
 ## Locking factories
 
 Initially, if no factories in given line are locked, no input/output can go beyond maximum.
@@ -148,18 +195,17 @@ In this mode calculator will answer the question: how many factories will be nee
 ![locking](./assets/locking.gif)
 </details>
 
-# Known problems and limitations
-
-## Factory dual dependent io
+## Setting objective
 
-When factory outputs two items or more, and these items directly or through production chain will be both feed to another factory at imperfect rate (i.e. first factory cannot dump all its output to second factory). In this case graph solver cannot solve factory io, so entire flow rate will be 0. This is not actually a bug, because real production chain of this type will also produce at zero rate after some time, because one output will be clogged. To overcome this, use two the same factories as input or output, or use 'fake' dump factory do dump exceeded resources.
+Initially graph is calculated using simple mode. In this mode graph solver tries to maximize overall io flow. This is acceptable for simple production chains, but may be adjusted for complex chains with multiple dependent output where maximizing one output will minimize other. It is recommended to set only one final product as main objective. Graph solver will first maximize main objective, and then will try to maximize secondary objective without hurting main objective. If any factory is set as objective - all other factories are excluded from maximization process.
 
-<details><summary>Example</summary>
+<details><summary>See in action</summary>
 
-![limitation-ratio](./assets/limitation-ratio1.png)
-![limitation-ratio](./assets/limitation-ratio2.png)
+![locking](./assets/objective.gif)
 </details>
 
+# Known problems and limitations
+
 ## Too much flow difference between connected factories
 
 When one factory produces/consumes at much higher ratio, than other connected factory (1000x or more), and their numbers are not integers, calculator fails to determine correct count due to insufficient precision. To fix this issue, precision should be set to other (lower) value, although it may not be enough for some cases.