maint: patch: v0.4 (#1034)

This is an emergency patch due to several issues that our tests did not
catch. This will become the new v0.4 release commit.

This commit does two things:
1. Reverts `BatchSimulate` from a top-level import to how it was
imported previously, which now requires manual import, as shown in its
example. I've added relevant instructions in the example that
indicates it requires some extra dependencies to function.
2. Adds a line in `setup.py` which is required for `setup.py` use (but
not `pyproject.toml`) that indicates to the relevant Python Packaging
repository that the README is in markdown format. I've also be
re-writing the "How to make a release" guide a bunch, including
reversing the order of instructings for `twine` uploading vs testing the
distributable.

It turns out that the reason `BatchSimulate` was not added to the
existing API documentation is related to a "blind spot" in our tests:
neither our units tests nor documentation tests actually test a "minimal
install" of simply:
`pip install hnn_core`
*without* including various extras. It turns that doing the above
command in a fresh environment of the previous master branch is actually
broken: this is due to `BatchSimulate`'s import dependence on `joblib`,
which is only included in the `[parallel]` dependencies. Because I
recently added `BatchSimulate` as a top-level import, but all of our
tests automatically install the `joblib` dependency, this was not
caught. I apologize for the error, and I will make a future PR that adds
additional steps to our unit tests that *progressively* install the
dependencies of minimal and, later, extra dependencies of hnn-core,
before proceeding to the existing unit tests.

Normally, it would be best to propagate this change as a "patch" release
such as v0.4.1, but we currently do not follow Semantic Versioning, and
furthermore it has yet to be tested if our documentation systems works
with Semantic Versioning indexing (or how it can be made to be). This is
another change we should make soon in the future.

Depending on the tests and more install testing, this will likely become
the new v0.4 release commit because the Python-packaged version had not
yet been pushed to Pypi (immutable), while other metadata (such as the
documentation and git tags) are mutable.

Author: asoplata

doc/api.rst

@@ -24,7 +24,6 @@ Simulation (:py:mod:`hnn_core`):
    Cell
    CellResponse
    pick_connection
-   BatchSimulate
 
 Network Models (:py:mod:`hnn_core`):
 ------------------------------------
@@ -101,7 +100,6 @@ Parallel backends (:py:mod:`hnn_core.parallel_backends`):
    MPIBackend
    JoblibBackend
 
-
 Input and Output:
 -----------------
 

doc/whats_new.md

@@ -13,7 +13,7 @@ v0.4 represents a major milestone in development of `hnn_core` and the HNN ecosy
 
 - `hnn_core` now includes a fully-tested and robust GUI of its own. The `hnn_core` GUI was present as a prototype in v0.3, but it is now ready for production. New features and visual improvements will still be coming to it in the future, such as the ability to use optimization. See our new [Install page](https://jonescompneurolab.github.io/hnn-core/dev/install.html) for ways to install it, and we have already begun incorporating it into a new, fresh series of tutorials for our upcoming revamp of the HNN website. If you have installed it, you can start the GUI using `hnn-gui` in your terminal/command prompt window.
 
-- The `BatchSimulate` class: Thanks to [Abdul Samad Siddiqui][] and Google Summer of Code 2024, there is now the capability to run "batches" of simulations across multiple parameter sets, enabling easy analysis and simulation of behavior across parameter sweeps. See our [example for more details](https://jonescompneurolab.github.io/hnn-core/dev/auto_examples/howto/plot_batch_simulate.html#sphx-glr-auto-examples-howto-plot-batch-simulate-py). Note that currently, only its `loky` backend is supported.
+- The `BatchSimulate` class: Thanks to [Abdul Samad Siddiqui][] and Google Summer of Code 2024, there is now the capability to run "batches" of simulations across multiple parameter sets, enabling easy analysis and simulation of behavior across parameter sweeps. See our [example for more details](https://jonescompneurolab.github.io/hnn-core/dev/auto_examples/howto/plot_batch_simulate.html#sphx-glr-auto-examples-howto-plot-batch-simulate-py). Note that currently, only its `loky` backend is supported, and the `"hnn-core[parallel]"` dependencies must be installed for it to be used.
 
 - Significant improvements to the API, documentation, and pedagogical examples [especially for Optimization](https://jonescompneurolab.github.io/hnn-core/stable/auto_examples/howto/optimize_evoked.html#sphx-glr-auto-examples-howto-optimize-evoked-py), among others.
 
@@ -129,8 +129,10 @@ v0.4 represents a major milestone in development of `hnn_core` and the HNN ecosy
 - Add function {func}`~hnn_core.params.convert_to_json` to convert legacy param and json
   files to new json format, by [George Dang][] in {gh}`772`
 
-- Add {class}`~hnn_core.BatchSimulate` for batch simulation capability, by [Abdul Samad
-  Siddiqui][] in {gh}`782`
+- Add
+  [`BatchSimulate`](https://jonescompneurolab.github.io/hnn-core/dev/auto_examples/howto/plot_batch_simulate.html#sphx-glr-auto-examples-howto-plot-batch-simulate-py)
+  class for batch simulation capability, by [Abdul Samad Siddiqui][]
+  in {gh}`782`
 
 - Recorded calcium concentration from the soma, as well as all sections, are enabled by
   setting `record_ca` to `soma` or `all` in {func}`~hnn_core.simulate_dipole`.
@@ -141,8 +143,9 @@ v0.4 represents a major milestone in development of `hnn_core` and the HNN ecosy
   colormap, and interpolation method to smoothen CSD plot, by [Katharina Duecker][] in
   {gh}`815`
 
-- Refactor and improve documentation for {class}`~hnn_core.BatchSimulate`, by [Abdul
-  Samad Siddiqui][] in {gh}`830` and {gh}`857`
+- Refactor and improve documentation for
+  [`BatchSimulate`](https://jonescompneurolab.github.io/hnn-core/dev/auto_examples/howto/plot_batch_simulate.html#sphx-glr-auto-examples-howto-plot-batch-simulate-py), by [Abdul Samad Siddiqui][]
+  in {gh}`830` and {gh}`857`
 
 - Add argument to change colors of `plot_spikes_raster`, shortened line lengths to
   prevent overlap, and added an argument for custom cell types, by [George Dang][] in

examples/howto/plot_batch_simulate.py

@@ -8,6 +8,12 @@
 for comprehensive analysis.
 """
 
+###############################################################################
+# Note that batch simulation requires you to install HNN-core with Joblib
+# parallel support, which you can do by installing it with
+# ``pip install "hnn_core[parallel]"``
+
+
 # Authors: Abdul Samad Siddiqui <[email protected]>
 #          Nick Tolley <[email protected]>
 #          Ryan Thorpe <[email protected]>
@@ -21,7 +27,7 @@
 import matplotlib.pyplot as plt
 import numpy as np
 
-from hnn_core import BatchSimulate
+from hnn_core.batch_simulate import BatchSimulate
 from hnn_core import jones_2009_model
 
 # The number of cores may need modifying depending on your current machine.

hnn_core/__init__.py

@@ -6,6 +6,5 @@
 from .cell_response import CellResponse, read_spikes
 from .cells_default import pyramidal, basket
 from .parallel_backends import MPIBackend, JoblibBackend
-from .batch_simulate import BatchSimulate
 
 __version__ = '0.4'

setup.py

@@ -97,6 +97,7 @@ def run(self):
           version=version,
           download_url=DOWNLOAD_URL,
           long_description=open('README.md').read(),
+          long_description_content_type='text/markdown',
           classifiers=[
               'Intended Audience :: Science/Research',
               'Intended Audience :: Developers',