docs: add simulation tutorial, fix typos

CONTRIBUTING.md

@@ -31,7 +31,7 @@ If you want to propose something new (new feature, extension, bugfix, documentat
 1. **Open an issue** and chat with everyone to make sure your contribution would fit nicely with the project.
 1. **Fork** this repo (click the _fork_ button on GitHub)
 2. **Follow the initial setup** described in the section below
-3. **Create a separate branch** that will hold your contribution
+3. **Create a separate branch** that will hold your contribution with any name (e.g. `feat/my_feature`)
 4. **Make your changes** 🪄 and stage them with `git add .`
 5. **Check your changes** with `pre-commit run`. If some of your changes do not follow the conventions, they will automatically be fixed. Take a look at the proposed changes and run `git add . && pre-commit run` again until all checks pass.
 6. **Commit** your contributions using the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) naming standard (e.g. `feat(readme): added something cool`)
@@ -45,6 +45,7 @@ For your next contributions, you can simply update your fork and start from step
 1. Clone your fork using the `--recursive` option to include the [`finary_api`](https://github.com/lasconic/finary) submodule:
 ```sh
 git clone --recursive https://github.com/YOUR_GITHUB_USERNAME/finalynx.git
+cd finalynx
 # If you forgot --recursive, run: git submodule update --init --recursive
 ```
 2. Install [`poetry`](https://python-poetry.org/) which manages the project dependencies, and get all dependencies needed to work on this project:

docs/quickstart/tutorials.md

@@ -14,11 +14,16 @@ Learn how to use the general tool's features before diving into your investments
 
 ## 2. Portfolio
 Now, you can set your own portfolio tree and watch your structure be built once you run Finalynx!
-- [**Tutorial 8:**](https://github.com/MadeInPierre/finalynx/blob/main/examples/tutorials/2_portfolio/8_structure.py) Define your portfolio structure
-- [**Tutorial 9:**](https://github.com/MadeInPierre/finalynx/blob/main/examples/tutorials/2_portfolio/9_buckets.py) Buckets
-- [**Tutorial 10:**](https://github.com/MadeInPierre/finalynx/blob/main/examples/tutorials/2_portfolio/10_attributes.py) Asset classes and expected performance
-- [**Tutorial 11:**](https://github.com/MadeInPierre/finalynx/blob/main/examples/tutorials/2_portfolio/11_targets.py) Targets
-- [**Tutorial 12:**](https://github.com/MadeInPierre/finalynx/blob/main/examples/tutorials/2_portfolio/12_envelopes.py) Envelopes
+- [**Tutorial 1:**](https://github.com/MadeInPierre/finalynx/blob/main/examples/tutorials/2_portfolio/1_structure.py) Define your portfolio structure
+- [**Tutorial 2:**](https://github.com/MadeInPierre/finalynx/blob/main/examples/tutorials/2_portfolio/2_buckets.py) Buckets
+- [**Tutorial 3:**](https://github.com/MadeInPierre/finalynx/blob/main/examples/tutorials/2_portfolio/3_attributes.py) Asset classes and expected performance
+- [**Tutorial 4:**](https://github.com/MadeInPierre/finalynx/blob/main/examples/tutorials/2_portfolio/4_targets.py) Targets
+- [**Tutorial 5:**](https://github.com/MadeInPierre/finalynx/blob/main/examples/tutorials/2_portfolio/5_envelopes.py) Envelopes
+
+## 3. Simulation
+Simulate your portfolio's future by adding your planned life events and salaries. Finalynx will automatically
+balance your investments based on the targets you have defined!
+- [**Tutorial 1:**](https://github.com/MadeInPierre/finalynx/blob/main/examples/tutorials/2_portfolio/1_structure.py) Define your portfolio structure
 
 Check back soon for more features, or [contribute](https://finalynx.readthedocs.io/en/latest/project/contributing.html) to see them appear here! 😄
 

examples/demo.py

@@ -26,7 +26,7 @@
 from finalynx import TargetRange, TargetMin, TargetMax, TargetRatio, TargetGlobalRatio  # noqa
 from finalynx import Folder, Line, Bucket, SharedFolder, Portfolio, FolderDisplay  # noqa
 from finalynx import AssetClass, AssetSubclass, Envelope, PEA, AV, PER  # noqa
-from finalynx import Copilot, Simulator, Assistant
+from finalynx import Assistant
 
 # Enable rich's features
 traceback.install()
@@ -194,26 +194,14 @@
         ],
     )
 
-    """
-    Define your life events and investment strategy on the long term
-    to simulate your portfolio's evolution.
-    """
-    scenario = Simulator()  # TODO Coming soon(ish)!
-
-    """
-    Define your monthly investment strategy to get automated investment
-    recommendations at each salary day.
-    """
-    copilot = Copilot()  # TODO Coming soon(ish-ish)!
-
     """
     Run the Assistant to get a complete overview of your portfolio!
     See the available options in the README file or the online documentation.
     """
     assistant = Assistant(
         portfolio,
-        buckets=[bucket_garanti],
-        envelopes=[my_bank, my_av],
+        buckets=[bucket_garanti],  # If you have defined buckets, you must pass them here as a list.
+        envelopes=[my_bank, my_av],  # If you have defined envelopes, you must pass them here as a list.
         ignore_orphans=True,  # Ignore fetched lines that you didn't reference in your portfolio.
         hide_amounts=False,  # Display your portfolio with dots instead of the real values (easier to share).
         hide_root=False,  # Display your portfolio without the root (cosmetic preference).

examples/tutorials/1_basics/1_minimal.py

@@ -1,6 +1,6 @@
 """
-Finalynx - Tutorial 1 - Minimal configuration
-=============================================
+Finalynx - Tutorial 1.1 - Minimal configuration
+===============================================
 
 
 This tutorial shows how to create the smallest valid portfolio

examples/tutorials/1_basics/2_theme.py

@@ -1,6 +1,6 @@
 """
-Finalynx - Tutorial 2 - Change the console color theme
-======================================================
+Finalynx - Tutorial 1.2 - Change the console color theme
+========================================================
 
 
 This tutorial shows how to change the console color theme if

examples/tutorials/1_basics/3_login.py

@@ -1,6 +1,6 @@
 """
-Finalynx - Tutorial 3 - Control login and cache
-===============================================
+Finalynx - Tutorial 1.3 - Control login and cache
+=================================================
 
 
 This tutorial shows how to clear the cache and login again to Finary

examples/tutorials/1_basics/4_export.py

@@ -1,6 +1,6 @@
 """
-Finalynx - Tutorial 4 - Export your portfolio to JSON logs
-==========================================================
+Finalynx - Tutorial 1.4 - Export your portfolio to JSON logs
+============================================================
 
 
 By default, Finalynx saves your portfolio in a JSON file everytime

examples/tutorials/1_basics/5_display_options.py

@@ -1,6 +1,6 @@
 """
-Finalynx - Tutorial 5 - Change some simple display options
-==========================================================
+Finalynx - Tutorial 1.5 - Change some simple display options
+============================================================
 
 
 This tutorial shows how to customize the rendering of your portfolio

examples/tutorials/1_basics/6_dashboard.py

@@ -1,6 +1,6 @@
 """
-Finalynx - Tutorial 6 - Launch an interactive dashboard
-=======================================================
+Finalynx - Tutorial 1.6 - Launch an interactive dashboard
+=========================================================
 
 
 This tutorial shows how to launch an interactive dashboard to explore your

examples/tutorials/1_basics/7_sources.py

@@ -1,11 +1,11 @@
 """
-Finalynx - Tutorial 7 - Fetch data from Finary and other sources
-================================================================
+Finalynx - Tutorial 1.7 - Fetch data from Finary and other sources
+==================================================================
 
-
-This tutorial shows how to launch an interactive dashboard to explore your
-portfolio in a web browser. The dashboard is currently in experimental mode,
-and contributors with web development skills are warmly welcome to improve it!
+This tutorial shows how to fetch data from Finary and other sources
+like RealT (and more to come depending on your contributions!).
+Finalynx lets you define your own portfolio structure which then
+gets filled with data from the sources you specify.
 
 See the available sources in the source code directly, please contribute! :)
 > https://github.com/MadeInPierre/finalynx/blob/main/finalynx/fetch/

examples/tutorials/2_portfolio/8_structure.py → examples/tutorials/2_portfolio/1_structure.py

@@ -1,6 +1,6 @@
 """
-Finalynx - Tutorial 7 - Define your portfolio structure (basics)
-================================================================
+Finalynx - Tutorial 2.1 - Define your portfolio structure (basics)
+==================================================================
 
 
 This tutorial shows how to define your portfolio structure in your configuration

examples/tutorials/2_portfolio/9_buckets.py → examples/tutorials/2_portfolio/2_buckets.py

@@ -1,6 +1,6 @@
 """
-Finalynx - Tutorial 8 - Define buckets to group similar lines
-=============================================================
+Finalynx - Tutorial 2.2 - Define buckets to group similar lines
+===============================================================
 
 
 This tutorial shows how to define buckets to group similar lines together.

examples/tutorials/2_portfolio/10_attributes.py → examples/tutorials/2_portfolio/3_attributes.py

@@ -1,6 +1,6 @@
 """
-Finalynx - Tutorial 9 - Set custom attributes for your lines
-===============================================================
+Finalynx - Tutorial 2.3 - Set custom attributes for your lines
+=================================================================
 
 
 This tutorial shows how to define custom attributes for your lines, which include:

examples/tutorials/2_portfolio/11_targets.py → examples/tutorials/2_portfolio/4_targets.py

@@ -1,6 +1,6 @@
 """
-Finalynx - Tutorial 10 - Set investment targets for your lines
-==============================================================
+Finalynx - Tutorial 2.4 - Set investment targets for your lines
+================================================================
 
 
 This tutorial shows how to define investment targets for your lines. For each node

examples/tutorials/2_portfolio/12_envelopes.py → examples/tutorials/2_portfolio/5_envelopes.py

@@ -1,6 +1,6 @@
 """
-Finalynx - Tutorial 12 - Set envelopes for your lines
-=====================================================
+Finalynx - Tutorial 2.5 - Set envelopes for your lines
+=======================================================
 
 
 This tutorial shows how to define envelopes for your lines. An envelope is a

examples/tutorials/3_simulation/1_basics.py

@@ -0,0 +1,84 @@
+"""
+Finalynx - Tutorial 3.1 - Simulate your portfolio's future
+==========================================================
+
+
+This tutorial shows how to simulate your portfolio's future by automagically:
+- Applying the recommendations made by Finalynx to your portfolio,
+- Applying the expected yearly performance of each line (specified by you),
+- Reducing your portfolio's value due to inflation,
+- Adding your monthly salary each month.
+
+By default, the first three points are enabled, you can disable them by setting
+the `default_events` option to `False` in the `Simulation` constructor.
+
+
+See the online documentation for the list of available pre-defined envelopes:
+> https://github.com/MadeInPierre/finalynx/blob/main/finalynx/portfolio/envelopes.py
+
+Try it out by running:
+> python3 examples/tutorials/12_envelopes.py
+
+See explanations and details in the online documentation at:
+> https://finalynx.readthedocs.io
+"""
+# noreorder
+from finalynx import Assistant, Portfolio, Line
+from finalynx import Simulation, Event, Salary, AddLineAmount, date
+
+""" [SIMULATION BASICS] -------------------------------------------------------
+The simulator can apply `Actions` wrapped around an `Event` instance. Events
+define when to perform the action, and can define an optional `Recurrence` to
+perform the action regularly (e.g. every month, at the end of each year, ...).
+
+There are currently three supported actions for now:
+- **ApplyPerformance:** Change the amounts of each `Line` depending on the
+  specified `LinePerf` expected investment performance. By default, this
+  action is already added in the list of events in the configuration and
+  executes on each December 31st.
+- **AutoBalance:** For folders and lines that use `TargetRatio` targets,
+  Finalynx will automatically apply the ideal amounts for each `Line`.
+  This corresponds to following the Finalynx recommendations. By default,
+  this event is automatically added and executed every 3 months.
+- **Salary**: Specify which `Line` in the portfolio should receive a specific
+  amount each month. This class is simply a shortcut to:
+
+  ```python
+  Event(AddLineAmount(your_account, 2500), recurrence=MonthlyRecurrence(day_of_the_month, until=end_date))
+  ```
+
+By default, the simulation runs for 100 years.
+
+To activate the simulator with the default events, add the following to your config:
+"""
+
+Assistant(Portfolio(), simulation=Simulation()).run()  # activate the simulation (with default behavior)
+
+"""
+Some other parameters can be set:
+"""
+
+
+livreta = Line("Livret A")  # Create a line before the portfolio to be able to reference it
+
+portfolio = Portfolio(children=[livreta])  # Create your portfolio with the line included anywhere in it
+
+
+Assistant(
+    portfolio,
+    buckets=[],  # Create a list with the references to your buckets (if any, none here)
+    envelopes=[],  # Create a list with the references to your envelopes (if any, none here)
+    # ... other options,
+    simulation=Simulation(
+        events=[  # Your personal config of events (salaries for now, more coming soon!)
+            Salary(livreta, income=2300, expenses=1400, end_date=date(2024, 11, 30)),
+            Event(AddLineAmount(livreta, 3500), planned_date=date(2024, 4, 10), name="Prime"),
+            Event(AddLineAmount(livreta, 3500), planned_date=date(2025, 4, 10), name="Prime"),
+            Salary(livreta, income=3000, expenses=2000, start_date=date(2025, 1, 1), name="Futur Job"),
+        ],
+        inflation=3.0,  # Percentage of inflation, will reduce each line's performance by this much
+        end_date=date(2063, 4, 5),  # Defaults to 100 years after today
+        step_years=5,  # Show a summary of the portfolio's total worth every X years in the console
+        default_events=True,  # Add default events to the ones specified above, defaults to True
+    ),
+).run()

finalynx/assistant.py

@@ -379,10 +379,10 @@ def export_json(self, dirpath: str) -> None:
                 f.write(json.dumps(final_dict, indent=4))
             console.log(f"Saved current portfolio to '{full_path}'")
         except FileNotFoundError:
-            console.log("[red][bold]Error:[/] Can't find the folder to save the portfolio to JSON. Three options:")
-            console.log("[red]  1. Disable export using --no-export")
-            console.log("[red]  2. Create a folder called logs/ in this folder (default folder)")
-            console.log("[red]  3. Set your own export directory using --export-dir=your/path/to/dir/")
+            console.log("[yellow][bold]Warning:[/] Can't find the folder to save the portfolio to JSON. Three options:")
+            console.log("[yellow]  1. Disable export using --no-export")
+            console.log("[yellow]  2. Create a folder called logs/ in this folder (default folder)")
+            console.log("[yellow]  3. Set your own export directory using --export-dir=your/path/to/dir/")
 
     def export_img(
         self,

finalynx/portfolio/folder.py

@@ -243,7 +243,7 @@ def process(self) -> None:
                 total_ratio += child.target.target_ratio
 
         if total_ratio != 0 and total_ratio != 100:
-            console.log(f"[yellow][bold]WARNING:[/] Folder '{self.name}' total ratio should sum to 100.")
+            console.log(f"[yellow][bold]Warning:[/] Folder '{self.name}' total ratio should sum to 100.")
 
     def match_lines(self, fetch_line: "FetchLine") -> List[Line]:
         """Used by the `fetch` subpackage to