BETSE 1.4.1: The Resurrection of BETSE

Welcome to BETSE 1.4.1, the first stable release of BETSE in (almost exactly) two years! Let's model some bioelectricity. 🥳

Install All this Good Stuff! 👇

Like all prior BETSE releases, BETSE 1.4.1 is publicly available via both pip + PyPI and conda + @conda-forge. Pick your open-source packaging poison solution:

• "I choose pip!" Excellent choice. Everyone feels peppy with pip:

  pip install --upgrade betse

• "I choose conda!" Also excellent. You can't go wrong with reptiles:

  conda config --add channels conda-forge
  conda install betse

Verify That BETSE Still Behaves Itself! 👌

After upgrading to any new BETSE version (including BETSE 1.4.1), it's a great idea to validate that BETSE still behaves itself. Just run the betse try subcommand from a temporary directory you don't particularly care about: e.g.,

cd /tmp
betse try

You should see an animated plot of a sample bioelectric simulation subject to a cut profile (i.e., sudden removal of cells mimicking a tissue wound). If you see something other than that, see the "B-b-but Nothing Works..." section below. 😮‍💨

What's So Good about BETSE 1.4.1, Anyway? 🤔

Everything. Literally everything. BETSE 1.4.1 is a whole new computational beast.

Prior versions of BETSE (like BETSE 1.3.0) no longer run under a modern Python workflow. Incompatibilities with recent scientific dependencies (like NumPy 2.0.0, SciPy 1.14.0, and Matplotlib 3.9.0) render prior versions of BETSE all but unusable.

BETSE 1.4.1 resolves all outstanding issues, deprecations, exceptions, and warnings by:

• Requiring a modern version of CPython: CPython ≥ 3.11. 🌝
• Requiring recent versions of most scientific dependencies, including:
  • NumPy ≥ 2.0.0. ✔️
  • SciPy ≥ 1.14.0. ✔️
  • Matplotlib ≥ 3.9.0. ✔️
  • @beartype ≥ 0.18.0. ✔️
• Refactoring the BETSE build system from the antiquated setuptools + setup.py ^🤮 to Hatch + pyproject.toml. ^🥂
• Runtime type-checking the entire BETSE codebase with @beartype – a hyper-fast standards-compliant type-checker designed from the ground-up for scientific workloads. 😮

"B-b-but Nothing Works, Everything Is Busted, and My Paper Is Due in 5 Minutes!"

Having issues... again? Seeing a slew of exceptions? Drowning in a deluge of warnings? Fear not. We are here for you and your exciting research. Please submit:

• All issues and feature requests directly to our friendly issue tracker here on GitHub. Let us assuage your valid problems.
• All scientific inquiries and collaborative inspiration directly to Dr. Alexis Pietak at ResearchGate. Science!

This Is Where We Thank You 👏

The principal authors of BETSE – Dr. Alexis Pietak (@pietakio) and Cecil Curry (@leycec) – humbly thank everyone for your renewed interest in BETSE. Together, we will model all the bioelectricity.

We'd also like to congratulate Dr. Andre Norfleet on his recent explosive Cells 2024 submission: "Identification of Distinct, Quantitative Pattern Classes from Emergent Tissue-Scale hiPSC Bioelectric Properties". This super-exciting paper leverages BETSE to validate experimental bioelectric findings. Due in large part to this paper's high-profile inclusion in the Cells 2024 Special Issue "Multiscale Studies of Cell Behavior", we've fielded a sudden uptick of interest in using BETSE to validate similar findings and concern over the future well-being of BETSE.

Allow us to now say:

BETSE is here to stay.

And BETSE 1.4.1 is the proof in the bioelectric pudding.

betse refs/tags/v1.4.0

BETSE 1.4.0: The Resurrection of BETSE

Welcome to **BETSE 1.4.0,** the first stable release of BETSE in (*almost exactly*) two years! Let's model some bioelectricity. :partying_face:

Like all prior BETSE releases, **BETSE 1.4.0** is publicly available via both [`pip` + PyPI](https://pypi.org/project/betse) and [`conda` + @conda-forge](https://anaconda.org/conda-forge/betse). Pick your open-source packaging ~~poison~~ solution:

* **"I choose `pip`!"** *Excellent choice.* Everyone feels peppy with `pip`:

  ```bash
  pip install --upgrade betse
  ```

* **"I choose `conda`!"** *Also excellent.* You can't go wrong with reptiles:

  ```bash
  conda config --add channels conda-forge
  conda install betse
  ```

After upgrading to *any* new BETSE version (including **BETSE 1.4.0**), it's a great idea to validate that BETSE still behaves itself. Just run the ``betse try`` subcommand from a temporary directory you don't particularly care about: e.g.,

```bash
cd /tmp
betse try
```

You should see an animated plot of a sample bioelectric simulation subject to a **cut profile** (i.e., sudden removal of cells mimicking a tissue wound). If you see something *other* than that, see the "B-b-but Nothing Works..." section below. :face_exhaling:

**Everything.** Literally everything. **BETSE 1.4.0** is a whole new computational beast.

Prior versions of BETSE (like BETSE 1.3.0) no longer run under a modern Python workflow. Incompatibilities with recent scientific dependencies (like NumPy 2.0.0, SciPy 1.14.0, and Matplotlib 3.9.0) render prior versions of BETSE all but unusable.

**BETSE 1.4.0** resolves *all* outstanding issues, deprecations, exceptions, and warnings by:

* Requiring a modern version of CPython: **CPython ≥ 3.11.** :full_moon_with_face:
* Requiring recent versions of most scientific dependencies, including:
  * **NumPy ≥ 2.0.0.** :heavy_check_mark:
  * **SciPy ≥ 1.14.0.** :heavy_check_mark:
  * **Matplotlib ≥ 3.9.0.** :heavy_check_mark:
  * **@beartype ≥ 0.18.0.** :heavy_check_mark:
* Refactoring the BETSE build system from the antiquated `setuptools` + `setup.py` <sup> :vomiting_face: </sup> to [**Hatch**](https://github.com/pypa/hatch) + `pyproject.toml`. <sup> :clinking_glasses: </sup>
* Runtime type-checking the entire BETSE codebase with @beartype – a [hyper-fast standards-compliant type-checker designed from the ground-up for scientific workloads](https://github.com/beartype/beartype/). :open_mouth:

Having issues... *again*? Seeing a slew of exceptions? Drowning in a deluge of warnings? Fear not. We are here for you and your exciting research. Please submit:

* All [**issues** and **feature requests** directly to our friendly issue tracker here on **GitHub**](https://github.com/betsee/betse/issues). Let us assuage your valid problems.
* All [**scientific inquiries** and **collaborative inspiration** directly to Dr. Alexis Pietak at **ResearchGate**](https://www.researchgate.net/profile/Alexis-Pietak). Science!

The principal authors of BETSE – [Dr. Alexis Pietak (@pietakio)](https://www.researchgate.net/profile/Alexis-Pietak) and [Cecil Curry (@leycec)](https://github.com/leycec) – humbly thank *everyone* for your renewed interest in BETSE. Together, we will model all the bioelectricity.

We'd also like to congratulate [Dr. Andre Norfleet](https://bioengineering.gatech.edu/index.php/user/andre-norfleet) on his [recent explosive Cells 2024 submission: **"Identification of Distinct, Quantitative Pattern Classes from Emergent Tissue-Scale hiPSC Bioelectric Properties"**](https://www.mdpi.com/2073-4409/13/13/1136). This *super*-exciting paper leverages BETSE to validate experimental bioelectric findings. Due in large part to this paper's high-profile inclusion in the [Cells 2024 Special Issue **"Multiscale Studies of Cell Behavior"**](https://www.mdpi.com/journal/cells/special_issues/49AYA0UO06), we've fielded a sudden uptick of interest in using BETSE to validate similar findings *and* concern over the future well-being of BETSE.

Allow us to now say:

> **BETSE is here to stay.**

And BETSE 1.4.0 is the proof in the bioelectric pudding.

BETSE 1.3.0

This minor release brings titillating support for configuring wrapper logging and runtime type-checking wrapper parameters.

This minor release resolves 3 issues. Noteworthy changes include:

Features Added

• Wrapper logging configurability. The high-level betse.science.wrapper.BetseWrapper class now enables logging to be configured at instantiation time. Specifically, the BetseWrapper.__init__ method now accepts these optional logging-specific parameters:
  • log_filename, the relative or absolute filename of a file to append logging messages to. When running BETSE on a cluster, users are advised to set this parameter for each process-specific BetseWrapper instance to a filename isolated to that process. Doing so avoids non-deterministic failures when rotating log files, including a dreaded non-human-readable "OSError: [Errno 116] Stale file handle" exception emitted when attempting to log to a log file currently being rotated by a competing BETSE process.
  • log_level, a string-based enumeration configuring the global logging level (e.g., "ALL", "DEBUG", "NONE"). If specified, this global logging level overrides the optional verbose parameter accepted by various public methods of the BetseWrapper class.
• Wrapper parameter runtime type-checking. All parameters passed to all BetseWrapper methods are now type-checked at runtime via beartype, a performance-friendly third-party pure-Python package.

Dependencies Added

• Beartype ≥ 0.10.0. BETSE now requires a reasonably recent version of beartype as a mandatory runtime dependency.

Issues Resolved

• Fast solver Dm_cells export. BETSE's fast solver now properly exports Dm_cells as a function of time.

Deprecations Resolved

• license_file -> license_files in setup.cfg. This release resolves a mostly negligible setuptools deprecation warning concerning the deprecated license_file setting in the top-level setup.cfg file:

  /usr/lib/python3.8/site-packages/setuptools/config/setupcfg.py:508: SetuptoolsDeprecationWarning: The license_file parameter is deprecated, use license_files instead.

• numpy.distutil.__config__ -> numpy.__config__. This release resolves a deprecation warning emitted under NumPy ≥ 1.23.0 when importing anything from the numpy.distutil submodule. Specifically, this commit generalizes the betse.lib.numpy.numpys submodule to preferably import the actively maintained numpy.__config__ submodule under NumPy ≥ 1.23.0 before falling back to importing the deprecated numpy.distutil.__config__ submodule under NumPy < 1.23.0. Doing so improves the likelihood that BETSE will behave as expected under NumPy ≥ 1.24.0, where the deprecated numpy.distutil submodule is expected to be removed entirely.

Tests Improved

• Wrapper testing. The high-level betse.science.wrapper.BetseWrapper class against a barrage of integration tests, including:
  • test_wrapper_default(), exercising that class with default parameters running an initialization phase.
  • test_wrapper_logging(), exercising that class with various non-default logging parameters running an initialization phase.
• Test suite restructured. Our test suite has been restructured so as to ensure that lower-level unit tests are exercised before higher-level integration tests -- improving the readability of test failures when the former fail.

(Planiform plant form!)

BETSE 1.2.1

BETSE 1.2.0 released.

This minor release resolves a growing cacophony of compatibility issues that have accrued in the two-and-a-half years since BETSE's last prior stable release (i.e., BETSE 1.1.1 (Nicer Nestor) in the pre-pandemic twilight of November, 2019). BETSE authors gratefully thank Dr. Levin at the Levin Lab, Tufts University for his continued patronage of BETSE.

Noteworthy changes include:

Hosting Improved

• GitLab -> GitHub. BETSE's git repository has been officially migrated from our prior host at GitLab to our new host at GitHub, mostly so as to centralize the maintenance burden of continuous integration (CI) workflows across this and the upstream @beartype project. Specifically:
  • Our prior GitLab-specific GitLab-CI and Windows-specific Appveyor CI configurations have been supplanted wholesale with our standard GitHub-specific GitHub Actions CI workflows for both package testing and publication.
  • Our front-facing README.rst documentation has been trivially revised to reference GitHub rather than GitLab.
  • Our prior GitLab-specific tox.ini configuration and `doc/rst/RELEASE.rst documentation have been supplanted wholesale with actively maintained and more GitHub-friendly equivalents liberally harvested from our upstream @beartype project.

Compatibility Improved

• Python >= 3.9.0. BETSE now officially supports both the Python 3.9.x and 3.10.x series.
• macOS Aqua detection. BETSE now detects the macOS-specific Aqua display server with significantly more robust logic. Previously, that detection unexpectedly raised exceptions under continuous integration (CI) workflows hosted by GitHub Actions. Now, that detection has been generalized to be resilient against edge cases – including:
  • The absence of the core macOS /System/Library/Frameworks/Security.framework/Security library.
  • The absence of the OSError-specific strerror instance variable on low-level exceptions raised during this detection.
• Windows environment variable detection. BETSE now circumvents erroneous Windows-specific shell environments produced by the GitHub Actions Windows runner, which fails to define the critical %LOCALAPPDATA%, %APPDATA%, or %HOME shell environment variables. Specifically:
  • The betse.util.app.meta.AppMetaABC.dot_dirname() method now leverages the first of the following shell environment variables exported to the active Windows process via trivial iteration: %LOCALAPPDATA%, %APPDATA%, and our standard get_home_dirname() getter. Insanely, the GitHub Actions Windows runner fails to export the former two shell environment variables as well as the otherwise standard %HOME% shell environment variable, which doesn't leave BETSE with terribly many options in CI environments.
• Windows subdirectory detection. BETSE now circumvents the erroneous Windows-specific implementation of the standard os.path.commonpath() function, which unsafely raises an exception rather than safely returning False when passed two pathnames residing on different Windows drives (e.g., C:/, D:/). Our betse.util.path.dirs.is_subdir() tester now catches and coerces that unsafe exception into a safe return value of False.

Compatibility Broken

• Python < 3.8.0. This release officially breaks backward compatibility by dropping support for the Python 3.5.x, 3.6.x, and 3.7.x series. The former two have officially hit their End-of-Life (EOL); the latter is a half-year away from doing so and no longer worth officially supporting.
• PIL (Pillow) < 7.0.0. This release officially breaks backward compatibility by dropping support for PIL (Pillow) < 7.0.0. See below.

Dependencies Bumped

• NumPy ≥ 1.22.0. BETSE now requires NumPy ≥ 1.22.0, which dramatically modified the (admittedly private) install-time numpy.distutils.__config__ API describing how NumPy was linked against various external third-party shared libraries (e.g., BLAS, LAPACK) at install-time. Our betse.lib.numpy.numpys submodule now accesses that private NumPy API much more carefully – with robust future-proofing against predicted breakage by future NumPy releases breaking that API yet again.
• PIL (Pillow) ≥ 7.0.0. BETSE now requires PIL (Pillow) ≥ 7.0.0, which introduced the standard pillow.__version__ attribute and deprecated the non-standard pillow.PILLOW_VERSION attribute. Doing so renders the codebase incompatible with PIL (Pillow) < 7.0.0. Relatedly, The betse.util.py.module.pymodname.MODULE_NAME_TO_VERSION_ATTR_NAME dictionary has removed the non-standard PIL: 'PILLOW_VERSION' entry.
• pytest ≥ 5.4.0, which refactored the previously defined private _pytest.capture.CaptureManager._getcapture() method into the newly defined private _pytest.capture._getmulticapture() function, which the betse.lib.setuptools.command.supcmdtest submodule necessarily monkey-patches at test time to sanitize captured output for long-running tests.

Features Improved.

• Runtime dependency validation. BETSE now validates whether optional and mandatory dependencies satisfy requirements at application startup by manually validating dependency versions before deferring to increasingly unreliable setuptools-specific logic for doing so. Specifically:
  • The private betse.lib.libs._iter_requirement_commands() iterator has been generalized to accept items of the REQUIREMENT_NAME_TO_COMMANDS dictionary as codebase-agnostic tuples rather than codebase-specific betse.metadata.RequirementCommand instances.
  • In the betse.lib.setuptools.setuptool submodule:
    • The die_unless_requirement() validator and is_requirement() tester have been generalized to manually validate dependency versions before deferring to setuptools-specific logic for doing so.
    • The get_requirement_distribution_or_none() getter docstring has been revised to note that that getter should only be called as a latch-ditch fallback.
• Traceback handling. BETSE now drastically simplifies its handling of exception tracebacks. Previously, BETSE only printed tracebacks (i.e., call stack traces) for uncaught exceptions when explicitly passed either the -v or --verbose options at the command line. Clearly, this was bad. While admittedly non-human-readable and thus unsightly, tracebacks yield mission-critical insights into critical breakage. Tracebacks are often the only means that devs have of debugging issues in cloud-hosted continuous integration (CI) workflows providing no convenient filesystem (and hence logfile) access; likewise, tracebacks are the only means that end users have of forwarding tracebacks to devs for subsequent debugging. BETSE now always prints tracebacks to standard error (stderr) regardless of options passed at the command line or defined in a configuration file.

Issues Resolved.

• Matplotlib stream plotting exception. An exception previously raised by Matplotlib on animating streamplots has been resolved.
• NumPy auto-object array deprecations. All currently non-fatal numpy.VisibleDeprecationWarning warnings resulting from NumPy's recent deprecation of auto-object arrays (i.e., the implicit creation of one-dimensional NumPy arrays of Python list objects when passed ragged list of list objects with no uniform length) have been resolved. Where possible, these arrays have been reverted to standard non-NumPy list of list objects; in all other cases, these arrays have been explicitly coerced into non-auto object arrays.
• Widespread deprecations. A slew of other currently non-fatal deprecation warnings emitted by various third-party dependencies of BETSE have similarly been resolved.

Installation Improved

• Install-time Python version enforced. The minimum mandatory version of Python required by this project is now enforced at setuptools-based install time via the recently introduced python_requires setup() key in our top-level setup.py installer.
• pypa/setuptools#2353 and pypa/pip#6264. This release resolves recent catastrophic upstream breakage introduced by setuptools 50.0 and pip 22.2.0, the newest stable release of everyone's least favourite build tools. Sadly, doing so requires temporarily disabling project-wide support for the tooling-agnostic pyproject.toml file -- which setuptools and pip continually demonstrate that they are unwilling to sanely support.
• setuptools entry point. The betse command installed by our top-level setup.py installer now correctly runs. Previously, our installer inadvertently produced a broken betse command by incorrectly monkey-patching the setuptools installation process.

Tests Improved

• pytest warning resolved. BETSE's test suite no longer issues a non-fatal warning under recent pytest versions. Specifically, our top-level pytest.ini configuration file now explicitly lists all custom pytest marks applied by our test suite.
• pytest warnings filters. BETSE now defers to pytest warnings filters when detected as running under pytest at test-time, preventing BETSE's custom warnings filters from silently overwriting those predefined by pytest. Most test harnesses (including pytest) define sane default warnings filters as well as enabling users to externally configure warnings filters from project-wide configuration files. Ergo, the pytest harness knows better than we do.
• tox venv isolation validation. BETSE's test suite now sports significantly improved tox-specific validation of whether this suite is safely isolated to a virtual environment (venv), avoiding spurious test failures with otherwise valid pipelines. Specifically:
  • The top-level pytest-specific conftest.py plugin has been generalized by:
    • Refactoring the existing private _clean_imports() function to:
      • Treat zip...