From dcd66dccd5d479ddb6b037f768066dca63e2334c Mon Sep 17 00:00:00 2001
From: Nihat Engin Toklu <engin@nnaisense.com>
Date: Sat, 15 Jun 2024 00:56:09 +0200
Subject: [PATCH] Update general_usage.md (#107)

- Extend the general usage docs to mention the status object
- Move the result analysis snippets to outside of the main example
- Add link to the detailed status item explanations
---
 docs/user_guide/algorithm_usage.md |  2 +-
 docs/user_guide/general_usage.md   | 51 +++++++++++++++++++++++++++++-
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/docs/user_guide/algorithm_usage.md b/docs/user_guide/algorithm_usage.md
index f6f863b4..281be613 100644
--- a/docs/user_guide/algorithm_usage.md
+++ b/docs/user_guide/algorithm_usage.md
@@ -48,7 +48,7 @@ Each status property can be accessed by its name
 best_discovered_solution = searcher.status["best"]
 ```
 
-All algorithms currently implemented in EvoTorch applied to single-objective problems will *at least* have the following status properties:
+Algorithms currently implemented in EvoTorch applied to single-objective problems might have the following status properties:
 
 - `'best'`, the best discovered solution so far.
 - `'worst'`, the worst discovered solution so far.
diff --git a/docs/user_guide/general_usage.md b/docs/user_guide/general_usage.md
index 43d99847..27ecb59d 100644
--- a/docs/user_guide/general_usage.md
+++ b/docs/user_guide/general_usage.md
@@ -40,6 +40,55 @@ searcher.run(10)
 # Process the information accumulated by the loggers.
 ...
 progress = pandas_logger.to_dataframe()
-progress.mean_eval.plot()  # Display a graph of the evolutionary progress by using the pandas data frame
+progress.mean_eval.plot()  # Plot the evolutionary progress
 ...
+
+# We now analyze the current status using the dictionary-like status object.
+# The status object allows one to get evaluation results (i.e. fitness, etc.)
+# and decision values of the best solution in the population
+# (via the key "pop_best"), center of the search distribution
+# (via the key "center", in case a distribution-based evolutionary
+# algorithm is being used), etc.
+
+for status_key in searcher.iter_status_keys():
+    print("===", status_key, "===")
+    print(searcher.status[status_key])
+    print()
 ```
+
+## Extracting and analyzing results
+
+We now discuss additional ways of analyzing the results of the evolutionary computation. The following code snippets represent possible continuations to the code example above (or to codes similar to it). Therefore, we will continue to refer to the search algorithm as `searcher`.
+
+If the evolutionary algorithm that was used is distribution-based (such as [SNES][evotorch.algorithms.distributed.gaussian.SNES], [XNES][evotorch.algorithms.distributed.gaussian.XNES], [CEM][evotorch.algorithms.distributed.gaussian.CEM], [PGPE][evotorch.algorithms.distributed.gaussian.PGPE], [CMAES][evotorch.algorithms.distributed.cmaes.CMAES]), the status object includes an item with key `"center"`, representing the center (i.e. mean) of the search distribution as a [ReadOnlyTensor][evotorch.tools.readonlytensor.ReadOnlyTensor]:
+
+```python
+center_point_as_tensor = searcher.status["center"]
+```
+
+Algorithms such as [Cosyne][evotorch.algorithms.ga.Cosyne], [GeneticAlgorithm][evotorch.algorithms.ga.GeneticAlgorithm], etc. do not have a search distribution, therefore, they do not have a center point. However, the best solution of their last population can be obtained via the status key `"pop_best"`, as a [Solution][evotorch.core.Solution] object:
+
+```python
+solution_object = searcher.status["pop_best"]
+decision_values_as_tensor = solution_object.values
+evals_as_tensor = solution_object.evals  # fitness(es), evaluation data, etc.
+```
+
+If the [Problem][evotorch.core.Problem] object was initialized with `store_solution_stats=True` (which is enabled by default when the device of the Problem is "cpu"), the solution with the best fitness ever observed is available via the status key `"best"`:
+
+```python
+best_sln = searcher.status["best"]
+best_sln_decision_values = best_solution.values
+best_sln_evals = best_sln.evals  # fitness(s), evaluation data, etc.
+```
+
+Unless the search algorithm was initialized to work across remote actors (via `distributed=True`), the search algorithm keeps its last population accessible via the attribute named `population`.
+
+```python
+for solution in searcher.population:
+    print("Decision values:", solution.values)
+    print("Evaluation:", solution.evals)  # fitnesses, evaluation data, etc.
+    print()
+```
+
+Please see also [here](algorithm_usage.md#accessing-the-status) for details regarding the status items.