Add FAQ documentation page for users

[spjuhel]

User description

Changes proposed in this PR:

• Adds an FAQ page to the documentation

This PR fixes #178

PR Author Checklist

• If new release, is version bumped?
• Correct target branch selected (if unsure, select develop)
• Descriptive pull request title added
• Source branch up-to-date with target branch
• Documentation updated
• Tests passing

---

PR Type

Documentation

---

Description

• Adds comprehensive FAQ page addressing user questions

• Covers model calibration topics and temporal resolution

• Includes results interpretation and shock value guidance

---

Diagram Walkthrough

flowchart LR
  A["Documentation"] -->|"adds FAQ page"| B["boario-faq.rst"]
  B -->|"Model Calibration"| C["Temporal Resolution Guide"]
  B -->|"Results & Interpretation"| D["Shock Value Guidance"]

Loading

File Walkthrough

Relevant files

Documentation

boario-faq.rst New FAQ documentation with calibration and results guidance docs/source/boario-faq.rst Creates new FAQ documentation file with two main sections Model Calibration section covers temporal resolution variables and inventory duration concepts Results & Interpretation section addresses production shock value considerations Includes mathematical examples and cross-references to model documentation +63/-0

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
🟢	🎫 #178 🟢 Add an FAQ page to the documentation.
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Not Applicable: The PR only adds documentation (FAQ) with no executable code or critical actions to audit, so this control cannot be verified from the diff. Referred Code .. _boario-faq: ############### FAQ ############### This page lists questions that were raised by users so far and answers, do not hesitate to populate new questions by raising an issue on the GitHub repo. Section: Model Calibration ========================== **Q: What variables do I need to care about if I want to change the temporal resolution of the IOT (``iotable_year_to_temporal_unit_factor``)?** **A:** All the following variable are expressed as a ``iotable_year_to_temporal_unit_factor``th of a year (days if 365, trimesters if 3, months if 12, etc.). Default values often assume ``iotable_year_to_temporal_unit_factor`` is 365, so you will need to change them if you change ``iotable_year_to_temporal_unit_factor``: * **For the Model:** - ``rebuild_tau`` - ``alpha_tau`` - ``inventory_restoration_tau`` ... (clipped 42 lines)
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: No Error Paths: Only documentation content was added; there are no code paths or error handling to assess in this diff. Referred Code .. _boario-faq: ############### FAQ ############### This page lists questions that were raised by users so far and answers, do not hesitate to populate new questions by raising an issue on the GitHub repo. Section: Model Calibration ========================== **Q: What variables do I need to care about if I want to change the temporal resolution of the IOT (``iotable_year_to_temporal_unit_factor``)?** **A:** All the following variable are expressed as a ``iotable_year_to_temporal_unit_factor``th of a year (days if 365, trimesters if 3, months if 12, etc.). Default values often assume ``iotable_year_to_temporal_unit_factor`` is 365, so you will need to change them if you change ``iotable_year_to_temporal_unit_factor``: * **For the Model:** - ``rebuild_tau`` - ``alpha_tau`` - ``inventory_restoration_tau`` ... (clipped 42 lines)
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: No Inputs Added: The change is documentation-only and introduces no input handling or data flows to validate in this diff. Referred Code .. _boario-faq: ############### FAQ ############### This page lists questions that were raised by users so far and answers, do not hesitate to populate new questions by raising an issue on the GitHub repo. Section: Model Calibration ========================== **Q: What variables do I need to care about if I want to change the temporal resolution of the IOT (``iotable_year_to_temporal_unit_factor``)?** **A:** All the following variable are expressed as a ``iotable_year_to_temporal_unit_factor``th of a year (days if 365, trimesters if 3, months if 12, etc.). Default values often assume ``iotable_year_to_temporal_unit_factor`` is 365, so you will need to change them if you change ``iotable_year_to_temporal_unit_factor``: * **For the Model:** - ``rebuild_tau`` - ``alpha_tau`` - ``inventory_restoration_tau`` ... (clipped 42 lines)
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[spjuhel]

/review

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis ✅ 178 - Fully compliant Compliant requirements: Add an FAQ page to the documentation.

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Formatting/Markup The page mixes reStructuredText with inline LaTeX-style math ($...$) and a horizontal rule (---). Sphinx with the default reST parser may not render $...$ without the math extension and '---' isn't a standard reST horizontal rule. Consider using proper math directives (:math:) and a reST separator, or ensure the myst/MathJax setup supports current syntax. --- **Q: Is ``inv_duration`` a vector with the duration (like the variable name says & the model description page) or initial stocks (like the description of this variable says: Initial/Objective inventory vector)?** **A:** Yes ``inv_duration`` is a vector with the duration (initial and goal) of the inventory: it represents for each sector the theoretical amount of temporal unit during which an industry can produce without receiving new inputs from that sector. For instance {"Aluminium":30} would mean that industries start with enough Aluminium to produce their product for 30 days, and will try to maintain that level as a goal, with respect to their production (thus if their production decreases/increases, the absolute amount of Aluminium considered as a goal would become lower/greater.). **Stocks** (expressed as monetary values) are stored in ``"input_stocks"`` within ``sim.model`` (and updated at each step). You may also track their evolution by specifically asking when instantiating the ``Simulation`` object. But given it has a size $n_{industries} \times n_{inputs} \times n_{steps}$, it can grow in size very quickly so it is not tracked by default. --- Section: Results & Interpretation ================================= **Q: Why are relatively large production shock values (``EventArbitProd``) not producing meaningful results?** **A:** Please check whether the shock value is considering the **correct temporal resolution**. For example, a using a **20% shock** for a **10-day event** represents a reduced **daily** production by 20%, if you are using annual shock data, this would not match: $$\frac{10}{365} \times 0.2$$ (The IOT temporal resolution is annual unless changed). Therefore, the annual shock represented here is $\approx$ **0.5%** (0.005) annual production. Consistency Variable names alternate between 'main_inv_dur' and 'inv_duration'; ensure naming matches the API/docs elsewhere to avoid confusion. Also check 'EventArbitProd' is the exact class/event name used in the codebase. * **For the Model:** - ``rebuild_tau`` - ``alpha_tau`` - ``inventory_restoration_tau`` - ``overprod_tau`` - ``main_inv_dur`` * **For the Event/Impact Set Up:** - ``duration`` - ``recovery_tau`` - ``impact`` - ``occurrence`` * **For the Simulation:** - ``n_temporal_units_to_sim``. .. note:: The temporal resolution has not been extensively tested, and you will receive a warning if you are changing the ``iotable_year_to_temporal_unit_factor``. --- **Q: Is ``inv_duration`` a vector with the duration (like the variable name says & the model description page) or initial stocks (like the description of this variable says: Initial/Objective inventory vector)?** **A:** Yes ``inv_duration`` is a vector with the duration (initial and goal) of the inventory: it represents for each sector the theoretical amount of temporal unit during which an industry can produce without receiving new inputs from that sector. For instance {"Aluminium":30} would mean that industries start with enough Aluminium to produce their product for 30 days, and will try to maintain that level as a goal, with respect to their production (thus if their production decreases/increases, the absolute amount of Aluminium considered as a goal would become lower/greater.). **Stocks** (expressed as monetary values) are stored in ``"input_stocks"`` within ``sim.model`` (and updated at each step).

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Correct the annual shock calculation Rephrase the explanation of a shock event's impact on annual production to improve clarity and correct the calculated percentage from 0.5% to 0.55%. docs/source/boario-faq.rst [56-63] -For example, a using a **20% shock** for a **10-day event** represents a reduced **daily** production by 20%, -if you are using annual shock data, this would not match: +For example, using a **20% shock** for a **10-day event** represents a 20% reduction in **daily** production for the duration of the event. +If you are thinking in terms of annual production, this does not mean a 20% drop in annual output. The total loss of annual production from this event is calculated as: -$$\frac{10}{365} \times 0.2$$ +$$1 - (1 - 0.2 \times \frac{10}{365})$$ -(The IOT temporal resolution is annual unless changed). +(The IOT data is annual, and the default simulation step is daily). -Therefore, the annual shock represented here is $\approx$ **0.5%** (0.005) annual production. +Therefore, the total loss of annual production from this 10-day event is $\approx$ **0.55%** (0.0055). Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies that the term 'annual shock' is confusing and improves the explanation's clarity. It also corrects the calculated value from 0.5% to the more accurate 0.55%, which helps users better understand the model's behavior.	Low
Update