owlplanner 2025.12.20__py3-none-any.whl → 2026.2.2__py3-none-any.whl

owlplanner/__init__.py

@@ -1,6 +1,25 @@
+"""
+Owl planner package initialization and public API exports.
+
+Copyright (C) 2025-2026 The Owlplanner Authors
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+
 from owlplanner.plan import Plan                                              # noqa: F401
 from owlplanner.plan import clone                                             # noqa: F401
-from owlplanner.config import readConfig                                      # noqa: F401
+from owlplanner.config import readConfig, saveConfig                          # noqa: F401
 from owlplanner.rates import getRatesDistributions                            # noqa: F401
 from owlplanner.version import __version__                                    # noqa: F401
 

owlplanner/abcapi.py

@@ -1,25 +1,25 @@
 """
+Abstract API for building linear programming constraint matrices.
 
-Owl/abcapi
----
+This module provides a solver-neutral API to build constraint matrices and
+objective functions line by line, abstracting the building process to enable
+use of various solvers (MOSEK, HiGHS, etc.) for comparison. The name ABCAPI
+refers to A (matrix), B (bounds), C (constraints).
 
-A retirement planner using linear programming optimization.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
-See companion document for a complete explanation and description
-of all variables and parameters.
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
 
-This file contains basic functions to build a constraint matrix and
-objective function line by line. This is used to abstract the
-building of the constraint matrix in order to be able to use various
-solvers for comparison.
-
-This approach has been successful with the MOSEK and the HiGHS solvers.
-A for matrix, B for bounds, C for constraints. Thus the name ABCAPI.
-
-Copyright © 2024 - Martin-D. Lacasse
-
-Disclaimers: This code is for educational purposes only and does not constitute financial advice.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
 
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 import numpy as np
@@ -176,7 +176,7 @@ class Bounds:
         self.ind.append(ii)
         self.lb.append(lb)
         self.ub.append(ub)
-        if lb == ub:
+        if np.isclose(lb, ub):
             self.key.append("fx")
         elif ub == np.inf and lb == -np.inf:
             self.key.append("fr")
@@ -204,6 +204,7 @@ class Bounds:
         return lb, ub
 
     def integralityArray(self):
+        # All variables continuous by default.
         integrality = np.zeros(self.nvars, dtype=int)
         for ii in range(len(self.integrality)):
             integrality[self.integrality[ii]] = 1

owlplanner/cli/README.md

@@ -0,0 +1,50 @@
+# OWLCLI - a Command Line Interface for OWL
+
+OWLCLI is a command line interface tool to streamline the listing, running and experimenting with OWL plan files outside the streamlit interface.
+
+## Installation
+
+OWLCLI is installed with the owlplanner module. Once OWLPLANNER is installed, owlcli can be run from the command line. 
+
+## Usage
+
+At present, OWLCLI provides two commands: `list` and `run`.
+
+```bash
+❯ owlcli list
+```
+
+This command will list all the available OWL .toml plan files in the current directory.
+
+To list all the available OWL plan files in the `examples` directory, relative to the current directory, use:
+
+```bash
+❯ owlcli list examples
+FILE                           PLAN NAME             TIME LISTS FILE
+--------------------------------------------------------------------------------
+Case_jack+jill                 jack+jill             ✓HFP_jack+jill.xlsx
+Case_joe                       joe                   ✓HFP_joe.xlsx
+Case_john+sally                john+sally            ✓HFP_john+sally.xlsx
+Case_jon+jane                  Jon+Jane              ✗HFP_jon+jane.xslx
+Case_kim+sam-bequest           kim+sam-bequest       ✓HFP_kim+sam.xlsx
+Case_kim+sam-spending          kim+sam-spending      ✓HFP_kim+sam.xlsx
+case_drawdowncalc-comparison-1 drawdowncalc-com...   ✗edited values
+```
+
+The listing shows the file name, plan name and Household Financial Plan file (timeListsFile) associated with each plan.
+
+✓ indicates that the Household Financial Plan file listed in the OWL Plan file exists.
+✗ indicates that the Household Financial Plan file was not found.
+*edited values* indicates that the plan file may have been changed since the Household Financial Plan file was created.
+
+
+To run an OWL plan file, use the `run` command followed by the plan file name:
+
+```bash
+❯ owlcli run examples/Case_kim+sam-spending
+Case status: solved
+Results saved to: examples/Case_kim+sam-spending_results.xlsx
+```
+
+This example runs the `Case_kim+sam-spending` plan file located in the `examples` directory. The results of the run are saved to a new Excel file with `_results.xlsx` appended to the original plan file name.  A copy of the input OWL plan file is saved as the new first tab in the Excel file.
+

owlplanner/cli/_main.py

@@ -0,0 +1,52 @@
+"""
+Command-line interface main entry point for Owl retirement planner.
+
+This module provides the main CLI group and command registration for the
+Owl command-line interface.
+
+Copyright (C) 2025-2026 The Owlplanner Authors
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+
+import click
+
+
+from .cli_logging import configure_logging, LOG_LEVELS
+from .cmd_list import cmd_list
+from .cmd_run import cmd_run
+
+
+@click.group()
+@click.option(
+    "--log-level",
+    type=click.Choice(LOG_LEVELS, case_sensitive=False),
+    default="INFO",
+    show_default=True,
+    help="Set logging verbosity.",
+)
+@click.pass_context
+def cli(ctx, log_level: str):
+    """SSG command-line interface."""
+    ctx.ensure_object(dict)
+    ctx.obj["log_level"] = log_level.upper()
+
+    configure_logging(log_level)
+
+
+cli.add_command(cmd_list)
+cli.add_command(cmd_run)
+
+if __name__ == "__main__":
+    cli()

owlplanner/cli/cli_logging.py

@@ -0,0 +1,56 @@
+"""
+CLI logging configuration utilities.
+
+This module provides logging configuration functions for the command-line
+interface, including log level management and formatting.
+
+Copyright (C) 2025-2026 The Owlplanner Authors
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+
+import sys
+from loguru import logger
+
+LOG_LEVELS = {
+    "TRACE",
+    "DEBUG",
+    "INFO",
+    "SUCCESS",
+    "WARNING",
+    "ERROR",
+    "CRITICAL",
+}
+
+
+def configure_logging(log_level: str = "INFO"):
+    log_level = log_level.upper()
+
+    if log_level not in LOG_LEVELS:
+        raise ValueError(f"Invalid log level: {log_level}")
+
+    logger.remove()  # remove default handler
+
+    logger.add(
+        sys.stderr,
+        level=log_level,
+        format=(
+            #            "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
+            "<level>{level:8}</level> | "
+            "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
+            "<level>{message}</level>"
+        ),
+        backtrace=(log_level == "TRACE"),
+        diagnose=(log_level == "TRACE"),
+    )

owlplanner/cli/cmd_list.py

@@ -0,0 +1,83 @@
+"""
+CLI command for listing retirement planning case files.
+
+This module provides the 'list' command for discovering and displaying
+information about retirement planning case files in a directory.
+
+Copyright (C) 2025-2026 The Owlplanner Authors
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+
+import click
+from pathlib import Path
+from loguru import logger
+
+import owlplanner as owl
+
+
+@click.command(name="list")
+@click.argument(
+    "directory",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=".",
+)
+def cmd_list(directory):
+    """
+    List OWL plan files in a directory.
+
+    DIRECTORY defaults to the current directory.
+    """
+    logger.debug(f"Listing plans in directory: {directory}")
+
+    toml_files = sorted(directory.glob("*.toml"))
+
+    if not toml_files:
+        click.echo("No .toml files found.")
+        return
+
+    plans = []
+
+    for filename in toml_files:
+        try:
+            logger.debug(f"Loading plan from {filename}")
+            plan = owl.readConfig(str(filename), logstreams="loguru", readContributions=False)
+            plans.append((filename.stem, plan))
+        except Exception as e:
+            logger.warning(f"Failed to load {filename}: {e}")
+
+    if not plans:
+        click.echo("No valid OWL plans found.")
+        return
+
+    click.echo(f"{'FILE':<30} {'PLAN NAME':<20} {' TIME LISTS FILE':<30}")
+    click.echo("-" * 80)
+
+    CHECK = "✓"
+    CROSS = "✗"
+
+    plan_dir = directory
+
+    for stem, plan in plans:
+        # Truncate plan name if needed
+        plan_name = plan._name
+        if len(plan_name) > 20:
+            plan_name = plan_name[:16] + "..."
+
+        # Check if timeListsFileName exists in current directory
+        tl_name = plan.timeListsFileName
+        exists = (plan_dir / tl_name).exists() if tl_name else False
+        mark = CHECK if exists else CROSS
+
+        click.echo(f"{stem:<30} {plan_name:<20}  {mark}{tl_name:<30}")

owlplanner/cli/cmd_run.py

@@ -0,0 +1,86 @@
+"""
+CLI command for running retirement planning cases.
+
+This module provides the 'run' command for executing retirement planning
+optimization from the command line.
+
+Copyright (C) 2025-2026 The Owlplanner Authors
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+
+import click
+from loguru import logger
+import owlplanner as owl
+from pathlib import Path
+
+
+def validate_toml(ctx, param, value: Path):
+    if value is None:
+        return None
+
+    # If no suffix, append .toml
+    if value.suffix == "":
+        value = value.with_suffix(".toml")
+
+    # Enforce .toml extension
+    if value.suffix.lower() != ".toml":
+        raise click.BadParameter("File must have a .toml extension")
+
+    # Check existence AFTER normalization
+    if not value.exists():
+        raise click.BadParameter(f"File '{value}' does not exist")
+
+    if not value.is_file():
+        raise click.BadParameter(f"'{value}' is not a file")
+
+    return value
+
+
+@click.command(name="run")
+@click.argument(
+    "filename",
+    type=click.Path(exists=False, dir_okay=False, path_type=Path),
+    callback=validate_toml,
+)
+@click.option(
+    "--with-config",
+    "with_config",
+    type=click.Choice(["no", "first", "last"], case_sensitive=False),
+    default="first",
+    show_default=True,
+    help="Include config TOML sheet at the first or last position.",
+)
+def cmd_run(filename: Path, with_config: str):
+    """Run the solver for an input OWL plan file.
+
+    FILENAME is the OWL plan file to run. If no extension is provided,
+    .toml will be appended. The file must exist.
+
+    An output Excel file with results will be created in the current directory.
+    The output filename is derived from the input filename by appending
+    '_results.xlsx' to the stem of the input filename.
+
+    Optionally include the case configuration as a TOML worksheet.
+
+    """
+    logger.debug(f"Executing the run command with file: {filename}")
+
+    plan = owl.readConfig(str(filename), logstreams="loguru", readContributions=True)
+    plan.solve(plan.objective, plan.solverOptions)
+    click.echo(f"Case status: {plan.caseStatus}")
+    if plan.caseStatus == "solved":
+        output_filename = filename.with_name(filename.stem + "_results.xlsx")
+        plan.saveWorkbook(basename=output_filename, overwrite=True, with_config=with_config)
+        click.echo(f"Results saved to: {output_filename}")