Fix Calmar Ratio zero-drawdown convention; add INITIAL_BALANCE market override

- get_calmar_ratio now returns inf when max_drawdown is 0 and CAGR is
  positive (matching the Sortino/Profit Factor/Omega Ratio convention
  from #599/#600), instead of a flat 0.0 regardless of CAGR sign.
- analyze_backtest_windows' inline Calmar computation aligned to match.
- add_market() now supports <MARKET>_OVERRIDE_INITIAL_BALANCE, closing
  the same override gap that already existed for api_key/secret_key/
  paper_trading/paper_trading_mode.

Author: MDUYN

docusaurus/docs/Getting Started/portfolio-configuration.md

@@ -118,21 +118,23 @@ BITVAVO_OVERRIDE_API_KEY=<sandbox-or-live-api-key>
 BITVAVO_OVERRIDE_SECRET_KEY=<sandbox-or-live-secret>
 BITVAVO_OVERRIDE_PAPER_TRADING=true
 BITVAVO_OVERRIDE_PAPER_TRADING_MODE=local
+BITVAVO_OVERRIDE_INITIAL_BALANCE=1000
 ```
 
 Unlike the fallback variables above, these **replace** the corresponding
 `add_market()` argument whenever set, regardless of what was passed:
 `<MARKET>_OVERRIDE_API_KEY` and `<MARKET>_OVERRIDE_SECRET_KEY` override
-`api_key`/`secret_key`, and `<MARKET>_OVERRIDE_PAPER_TRADING`/
+`api_key`/`secret_key`, `<MARKET>_OVERRIDE_PAPER_TRADING`/
 `<MARKET>_OVERRIDE_PAPER_TRADING_MODE` override `paper_trading`/
-`paper_trading_mode`. The prefix comes from the market already selected by
-the call — these variables never redirect `market` or `trading_symbol`
-themselves.
+`paper_trading_mode`, and `<MARKET>_OVERRIDE_INITIAL_BALANCE` overrides
+`initial_balance` — including a value hardcoded in an entry script. The
+prefix comes from the market already selected by the call — these
+variables never redirect `market` or `trading_symbol` themselves.
 
 Paper-trading booleans accept `true`/`false`, `yes`/`no`, `on`/`off`, and
 `1`/`0`, case-insensitively. Modes accept `auto`, `broker`, and `local`,
-also case-insensitively. Invalid values fail fast with
-`ImproperlyConfigured`.
+also case-insensitively. `INITIAL_BALANCE` must parse as a number.
+Invalid values fail fast with `ImproperlyConfigured`.
 
 These overrides apply only to `add_market()`. Directly constructed
 `PortfolioConfiguration` objects only read the general fallback variables

investing_algorithm_framework/analysis/backtest_window_analysis.py

@@ -177,7 +177,10 @@ def analyze_backtest_windows(
         ) * 100
         calmar = (
             annual_return / abs(max_drawdown)
-            if max_drawdown < 0 else 0.0
+            if max_drawdown < 0
+            # No drawdown at all. Same convention as get_calmar_ratio,
+            # get_sortino_ratio, get_profit_factor and get_omega_ratio.
+            else (float('inf') if annual_return > 0 else 0.0)
         )
 
         skew = float(pct.skew()) if len(pct) > 2 else float("nan")

investing_algorithm_framework/app/app.py

@@ -64,6 +64,21 @@ def _parse_environment_boolean(variable_name, fallback):
     )
 
 
+def _parse_environment_float(variable_name, fallback):
+    value = os.getenv(variable_name)
+
+    if value is None:
+        return fallback
+
+    try:
+        return float(value)
+    except ValueError:
+        raise ImproperlyConfigured(
+            f"{variable_name} environment variable {value!r} is not a "
+            f"valid number"
+        )
+
+
 def _build_strategy_universe_map(strategies, universe):
     """Thin wrapper around the domain helper of the same name; kept for
     backwards compatibility with code paths inside ``app.py``."""
@@ -2505,7 +2520,8 @@ def add_market(
                 initialization.
             initial_balance: Initial balance for the market. Falls
                 back to the ``INITIAL_BALANCE`` environment variable
-                when not given.
+                when not given. Overridden by
+                ``{MARKET}_OVERRIDE_INITIAL_BALANCE`` when set.
             fee_percentage: Default fee percentage for all trades
                 on this market (e.g. 0.1 for 0.1%). Can be overridden
                 per-symbol via TradingCost on the strategy.
@@ -2546,6 +2562,10 @@ def add_market(
                 f"{environment_prefix}_OVERRIDE_PAPER_TRADING",
                 paper_trading,
             )
+            initial_balance = _parse_environment_float(
+                f"{environment_prefix}_OVERRIDE_INITIAL_BALANCE",
+                initial_balance,
+            )
 
             paper_trading_mode_override = os.getenv(
                 f"{environment_prefix}_OVERRIDE_PAPER_TRADING_MODE"

investing_algorithm_framework/services/metrics/calmar_ratio.py

@@ -29,12 +29,16 @@ def get_calmar_ratio(snapshots: List[PortfolioSnapshot]):
             from the backtest report.
 
     Returns:
-        float: The Calmar Ratio.
+        float: The Calmar Ratio. Returns ``float('inf')`` when there was
+            no drawdown at all but CAGR is positive, and ``0.0`` when
+            there is no drawdown and no positive return (mirrors the
+            division-by-zero convention used by ``get_sortino_ratio``,
+            ``get_profit_factor`` and ``get_omega_ratio``).
     """
     cagr = get_cagr(snapshots)
     max_drawdown = get_max_drawdown(snapshots)
 
     if max_drawdown == 0 or max_drawdown is None:
-        return 0.0
+        return float('inf') if cagr > 0 else 0.0
 
     return cagr / max_drawdown

tests/app/test_add_market.py

@@ -139,6 +139,35 @@ def test_false_paper_trading_environment_overrides_true_argument(self):
         configuration = app.get_portfolio_configurations()[0]
         self.assertFalse(configuration.paper_trading)
 
+    def test_initial_balance_override_replaces_argument(self):
+        with patch.dict(
+            "os.environ",
+            {"BINANCE_OVERRIDE_INITIAL_BALANCE": "1000"},
+            clear=False,
+        ):
+            app = create_app(config={RESOURCE_DIRECTORY: self.resource_dir})
+            app.add_market(
+                market="binance",
+                trading_symbol="EUR",
+                initial_balance=400,
+            )
+
+        configuration = app.get_portfolio_configurations()[0]
+        self.assertEqual(1000.0, configuration.initial_balance)
+
+    def test_invalid_initial_balance_override_fails_fast(self):
+        with patch.dict(
+            "os.environ",
+            {"BINANCE_OVERRIDE_INITIAL_BALANCE": "not-a-number"},
+            clear=False,
+        ):
+            app = create_app(config={RESOURCE_DIRECTORY: self.resource_dir})
+            with self.assertRaisesRegex(
+                ImproperlyConfigured,
+                "BINANCE_OVERRIDE_INITIAL_BALANCE",
+            ):
+                app.add_market(market="binance", trading_symbol="EUR")
+
     def test_market_and_trading_symbol_arguments_are_not_overridden(self):
         with patch.dict(
             "os.environ",

tests/services/metrics/test_calmer_ratio.py

@@ -62,14 +62,18 @@ def test_typical_case(self):
     def test_calmar_ratio_zero_drawdown(self):
         """
         Test Calmar ratio when there are no drawdowns (only gains).
-        Should return 0.0 since we can't divide by zero.
+
+        There is no downside risk to divide by and CAGR is positive, so
+        the ratio is unbounded. This mirrors the division-by-zero
+        convention used by get_sortino_ratio, get_profit_factor and
+        get_omega_ratio.
         """
         report = self._create_report(
             [1000, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000],
             [datetime(2024, 1, i) for i in range(1, 11)]
         )
         ratio = get_calmar_ratio(report.portfolio_snapshots)
-        self.assertEqual(ratio, 0.0)
+        self.assertEqual(ratio, float('inf'))
 
     def test_calmar_ratio_with_only_drawdown(self):
         """