Update stochastic_transitions from develop

CHANGELOG.md

@@ -2,24 +2,92 @@
 
 This file records changes to the codebase grouped by version release. Unreleased changes are generally only present during development (relevant parts of the changelog can be written and saved in that section before a version number has been assigned)
 
-## [1.28.5] - 2023-06-28
+## [1.31.5] - 2026-05-26
+
+- Update optimization function for compatibility with latest `pyswarm` release
+- Update minimum Python version to 3.10 as previous versions are deprecated
+
+## [1.31.4] - 2026-01-28
+
+- Updated internal functions for Python 3.14 and Pandas 3.0.0
+
+## [1.31.3] - 2025-08-11
+
+- Changed initialization method to increase prioritization for characteristics with zero value. If a characteristic has a zero value, this will now automatically force included compartments to have a zero value. In practice, this means that it is less likely that frameworks will cause negative initial popsizes, so some frameworks that previously did not work will now initialize correctly.
+- Added `at.TimeSeries.clear()` to reset a time series while preserving the units. This function can be useful when updating the value of databook quantities programatically. 
+- Added a separate numerical tolerance used for initialization (`at.model.model_settings['initialization_tolerance']`) which permits more approximate initializations while still maintaining the same numerical tolerance for the rest of the integration.
+- Added another logging level (`at.VERBOSE`) which enables more targeted additional output
+
+- *Backwards-compatibility notes*
+
+- Some initializations might show numerical (e.g., `1e-10`) differences in their values due to the new algorithm. In a small number of cases (depending on the framework), it is possible that the updated initialization method could result in a slightly different initialization.  
+- The default initialization tolerance is now `1e-3` instead of `1e-6`, some models that previously raised a `BadInitialization` error will now run without error. Users should note that if it's necessary to guarantee an exact initialization, this tolerance should be reduced. 
+
+## [1.31.2] - 2025-06-26
+
+- Fix bug in creating databook if framework 'Databook pages' sheet contains multiple code names mapping to the same full name.
+
+## [1.31.1] - 2025-05-30
+
+- Switched from `setup.py` to `pyproject.toml`-based installation.
+
+## [1.31.0] - 2025-02-18
+
+- Framework definitions of compartments, characteristics, and parameters support a new column 'databook default all'. If set to 'y', then when a databook is produced, the data entry table will only contain a record for 'All' instead of having population-specific rows. Further manual editing of the tables is supported as normal. 
+
+## [1.30.0] - 2025-02-17
+
+- Automatic calibration can now selectively weight parts of the time series to select or prioritise a subset of time points.
+- Added YAML-based calibration support to Atomica, covered in Tutorial 7 in the online documentation.
+
+## [1.29.0] - 2024-10-30
+
+- `ProjectSettings` now computes the simulation time vector in a more robust way to reduce edge cases where the reported `sim_dt` doesn't match the input.
+- `ParameterSet.load_calibration()` now clears any existing initialization if the calibration being loaded does not contain an initialization. Previously, the absence of an 'initialization' sheet in the calibration would be treated as not making any change to the initialization. This could cause calibrations to become mixed if a calibration without an initialization was loaded after a calibration with an initialization. Now, a missing initialization sheet is treated as meaning 'no initialization' and any existing initialization will be cleared when the calibration is loaded. 
+- `Project.load_databook()` will no longer populate `Project.databook` when a `ProjectData` instance is supplied rather than a spreadsheet. The intention of `Project.databook` as opposed to `Project.data.to_spreadsheet()` is that the original databook may contain comments or other content that is not preserved when the databook is loaded into a `ProjectData` instance. Therefore, `Project.databook` serves as a record of the original inputs. However, in previous versions of Atomica, if a `ProjectData` instance was provided rather than a spreadsheet, `ProjectData.to_spreadsheet()` would be used to populate `Project.databook`. For large databooks, this can be computationally expensive and particularly affect the use case of passing in a preloaded databook to improve performance. Since the conversion of the `ProjectData` to a spreadsheet upon loading offers no functional difference to creating the spreadsheet from `Project.data` when required, Atomica no longer performs this conversion upfront.
+- `PlotData.time_aggregate()` now only interpolates if necessary, using simulated time points as much as possible.
+
+*Backwards-compatibility notes*
+
+- In some edge cases, the simulation time points in the output may be different. In those cases, the difference between simulation time points in the model output would not have matched the model input, although the correct time step would have been used to calculate parameter values. In these cases, there may be an extra time point in the model output. Re-running the model should produce results that are close to the original results.
+- If accessing `Project.databook`, in some cases this may now be `None` rather than an `sc.Spreadsheet()`. If that occurs, `Project.data.to_spreadsheet()` should be used to produce an equivalent spreadsheet. 
+- Time aggregation of `PlotData` may produce slightly different results due to the more accurate selection of time points in this version.
+- 
+## [1.28.7] - 2024-10-29
+
+- If aggregating characteristics with a denominator, weighted aggregations use the denominator of the quantity rather than the total population size to perform the weighting. This can be useful for quantities that are proportions of things other than the population size e.g., proportion of active infections that are diagnosed
+- If aggregating characteristics with a denominator, weighted aggregation will be used by default (rather than 'average')
+- Output aggregation of durations now uses 'sum' instead of 'average' by default
+- If no aggregation method is specified, the aggregation method will now be selected separately for each output
+- Population aggregation of non-number units now uses 'weighted' by default rather than 'average'
+
+*Backwards-compatibility notes*
+
+- Results obtained when aggregating characteristics with a denominator using the 'weighted' method will change. To reproduce the previous results, it is necessary to perform the population size weighting manually by removing the aggregation, then extracting the population sizes, and using those to aggregate the outputs. This is considered to be a rare use case because the updated result is a more useful weighting compared to the previous result.
+- Results obtained when aggregating characteristics with a denominator _without_ explicitly specifying a method will change, because 'weighted' aggregation is now used by default. 
+
+## [1.28.6] - 2024-07-12
+
+- Support entering `'total'` as the population name in auto-calibration measurables to calibrate aggregated values across populations in the model to aggregate values entered in the databook under a 'Total' population
+
+## [1.28.5] - 2024-06-28
 
 - Enable automated calibration of transfers and updated documentation to cover this feature
 
-## [1.28.4] - 2023-05-27
+## [1.28.4] - 2024-05-27
 
 - Added an option to save initial compartment sizes inside a `ParameterSet`. Importantly, this saved representation allows setting the initial _subcompartment_ sizes for a `TimedCompartment`. It therefore offers the possibility of initializing the model in a steady state computed from a previous simulation run, that would not be possible to initialize conventionally because standard initialization uniformly distributes people into the subcompartments of a timed compartment.  
 - Added `ParameterSet.make_constant` to facilitate constructing copies of `ParameterSet` instances that are constant over time.
 
-## [1.28.3] - 2023-05-16
+## [1.28.3] - 2024-05-16
 
 - Updated `at.Project()` to explicitly take in the settings arguments for `sim_start`, `sim_end`, and `sim_dt`. These are now applied after databooks are loaded, fixing a bug where these arguments would get overwritten when loading the databook.
 
-## [1.28.2] - 2023-04-05
+## [1.28.2] - 2024-04-05
 
 - `at.calibrate` now supports passing any additional arguments into the optimization function e.g., `sc.asd` allowing additional options for customizing the optimization. 
 
-## [1.28.1] - 2023-02-05
+## [1.28.1] - 2024-02-05
 
 - Updated various Pandas operations to improve compatibility with Pandas 2.2.0
 - Replaced 'probability' units with 'rate' units in many of the library example frameworks

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Atomica Development Team
+Copyright (c) 2017 - 2025 Atomica Development Team
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://dev.azure.com/AtomicaTeam/Atomica/_apis/build/status/atomicateam.atomica?branchName=master)](https://dev.azure.com/AtomicaTeam/Atomica/_build/latest?definitionId=1&branchName=master)
 
-[![PyPi version](https://badgen.net/pypi/v/atomica/)](https://pypi.com/project/atomica)
+[![PyPi version](https://badgen.net/pypi/v/atomica/)](https://pypi.org/project/atomica)
 
 Atomica is a simulation engine for compartmental models. It can be used to simulate disease epidemics, health care cascades, and many other things.
 

atomica/__init__.py

@@ -26,24 +26,27 @@
 import sys
 import logging
 
+VERBOSE = 15
+logging.addLevelName(VERBOSE, "VERBOSE")
 logger = logging.getLogger("atomica")
+logging.Logger.verbose = lambda self, msg, *args, **kwargs: self.log(VERBOSE, msg, *args, **kwargs)
 
 if not logger.handlers:
     # Only add handlers if they don't already exist in the module-level logger
     # This means that it's possible for the user to completely customize *a* logger called 'atomica'
     # prior to importing Atomica, and the user's custom logger won't be overwritten as long as it has
     # at least one handler already added. The use case was originally to suppress messages on import, but since
     # importing is silent now, it doesn't matter so much.
-    debug_handler = logging.StreamHandler(sys.stdout)  # info_handler will handle all messages below WARNING sending them to STDOUT
-    info_handler = logging.StreamHandler(sys.stdout)  # info_handler will handle all messages below WARNING sending them to STDOUT
+    debug_handler = logging.StreamHandler(sys.stdout)  # handle all messages below WARNING sending them to STDOUT
+    info_handler = logging.StreamHandler(sys.stdout)  # handle all messages below WARNING sending them to STDOUT
     warning_handler = logging.StreamHandler(sys.stderr)  # warning_handler will send all messages at or above WARNING to STDERR
 
-    debug_handler.setLevel(0)  # Handle all lower levels - the output should be filtered further by setting the logger level, not the handler level
-    info_handler.setLevel(logging.INFO)  # Handle all lower levels - the output should be filtered further by setting the logger level, not the handler level
+    debug_handler.setLevel(0)  # Handle all levels - the output is then filtered further by setting the logger level, not the handler level
+    info_handler.setLevel(logging.INFO)  # Handle levels INFO or higher
     warning_handler.setLevel(logging.WARNING)
 
-    debug_handler.addFilter(type("ThresholdFilter", (object,), {"filter": lambda x, logRecord: logRecord.levelno < logging.INFO})())  # Display anything INFO or higher
-    info_handler.addFilter(type("ThresholdFilter", (object,), {"filter": lambda x, logRecord: logRecord.levelno < logging.WARNING})())  # Don't display WARNING or higher
+    debug_handler.addFilter(type("ThresholdFilter", (object,), {"filter": lambda x, logRecord: logRecord.levelno < logging.INFO})())  # Display only messages below the INFO level
+    info_handler.addFilter(type("ThresholdFilter", (object,), {"filter": lambda x, logRecord: logRecord.levelno < logging.WARNING})())  # Display only messages below WARNING (the info_handler level already rejects anything below INFO)
 
     warning_formatter = logging.Formatter("%(levelname)s {%(filename)s:%(lineno)d} - %(message)s")
     warning_handler.setFormatter(warning_formatter)
@@ -56,12 +59,16 @@
     logger.addHandler(warning_handler)
     logger.setLevel("INFO")  # Set the overall log level
 
-from .version import version as __version__, versiondate as __versiondate__, gitinfo as __gitinfo__
 
-# Check scipy version
-import scipy
+# Get version information
+from .version import version as __version__, versiondate as __versiondate__
 import sciris as sc
+__gitinfo__ = sc.gitinfo(__file__)
+version.gitinfo = __gitinfo__ # Add back (so version.py does not require imports)
 
+
+# Check scipy version
+import scipy
 if sc.compareversions(scipy.__version__, "1.2.1") < 0:
     raise Exception(f"Atomica requires Scipy 1.2.1 or later - installed version is {scipy.__version__}")
 
@@ -95,3 +102,7 @@
 from .scenarios import *
 from .system import *
 from .utils import *
+
+import pathlib
+
+rootdir = pathlib.Path(__file__).parent.parent