nrn-patch 4.0.0__py2.py3-none-any.whl

nrn_patch-4.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Robin De Schepper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nrn_patch-4.0.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.1
+Name: nrn-patch
+Version: 4.0.0
+Summary: Quality of life patch for the NEURON simulator.
+Author-email: Robin De Schepper <robingilbert.deschepper@unipv.it>
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Requires-Dist: nmodl-glia[neuron]~=4.0
+Requires-Dist: errr~=1.2
+Requires-Dist: numpy~=1.21
+Requires-Dist: NEURON>=8.0,<10.0
+Requires-Dist: nrn-patch[test, docs] ; extra == "dev"
+Requires-Dist: pre-commit~=3.0 ; extra == "dev"
+Requires-Dist: black~=24.0 ; extra == "dev"
+Requires-Dist: sphinx~=7.2 ; extra == "docs"
+Requires-Dist: helveg--sphinx-code-tabs~=0.2 ; extra == "docs"
+Requires-Dist: sphinx-rtd-theme~=2.0 ; extra == "docs"
+Requires-Dist: mpi4py~=3.0 ; extra == "parallel"
+Requires-Dist: coverage~=7.0 ; extra == "test"
+Project-URL: Home, https://github.com/dbbs-lab/patch
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: parallel
+Provides-Extra: test
+
+![build](https://github.com/Helveg/patch/actions/workflows/main.yml/badge.svg)
+[![codecov](https://codecov.io/gh/Helveg/patch/branch/master/graph/badge.svg)](https://codecov.io/gh/Helveg/patch)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Documentation Status](https://readthedocs.org/projects/patch/badge/?version=latest)](https://patch.readthedocs.io/en/latest/?badge=latest)
+
+
+![Drop in replacement](patch.gif)
+
+_*No ducks were punched during the construction of this monkey patch._
+
+# Installation
+
+```
+pip install nrn-patch
+```
+
+## Minimal requirements
+
+* Python 3.8+
+* NEURON 8.0+
+
+# Philosophy
+
+Pythonic reinvention of the NEURON Python interface:
+
+  - **Drop-in replacement:** No breaking changes between Patch and NEURON. All
+    your code works as is. Patch automagically fixes bugs and reduces
+    complexity in NEURON by having an opinion, and adds new convenient methods.
+  - **Loud errors:** silent failures and gotchas are caught and raise
+    loud errors; so that when it runs, it runs.
+  - **Strong referencing:** Objects connected to each other will never disappear
+    until you disconnect them.
+  - **Demystified:** The simplest form of each instruction does the most obvious thing.
+    Patch frequently replaces 5 or more undocumented mystical voodoo steps by 1 clearly named function.
+  - **Just add water:** Serial or parallel, doesn't matter, `p.run()` will run your
+    simulation with no extra steps. No `load_file`, `finitialize`, `fadvance`, `run`,
+    `continuerun`, `tstop`, `set_maxstep`, `setup_transfer`, `setgid2node`, `gid_connect`,
+    `cell`, `outputcell`, `psolve` required.
+
+# Basic usage
+
+Use it like you would use NEURON. The wrapper doesn't make any changes to the interface,
+it just patches up some of the more frequent and ridiculous gotchas.
+
+Patch supplies a new interpreter `p`, the `PythonHocInterpreter` which wraps the
+standard HOC interpreter `h` provided by NEURON. Any objects returned will either be
+`PythonHocObject`'s wrapping their corresponding NEURON object, or whatever NEURON
+returns.
+
+When using just Patch the difference between NEURON and Patch objects is handled
+transparently, but if you wish to mix interpreters you can transform all Patch objects
+back to NEURON objects with `obj.__neuron__()`, or the `transform` function.
+
+## Example
+
+``` python
+from patch import p
+import glia as g
+
+section = p.Section()
+point_process = g.insert(section, "AMPA")
+point_process.stimulate(start=10, number=5, interval=10, weight=0.04)
+```
+
+`.stimulate` creates both the `NetCon` and `NetStim`, and sets their properties, and
+stores references to eachother so that Python doesn't garbage collect anything
+until we're done with it.
+
+Even when you forget to set values, the Patch defaults have a visible effect.
+Here we forget to set the duration of a voltage clamp, but by default it will
+be active the first 100ms of the simulation, so that you can see that the voltage
+clamp is in fact inserted and working, but you forgot to set the duration:
+
+```
+section.vclamp(holding=-70, voltage=20)
+```
+

nrn_patch-4.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+patch/__init__.py,sha256=RP-z1eF-iRlUZmTSQo3HgIU8jOQJ-Bq8KwTqB0yUy5c,1862
+patch/core.py,sha256=Ik-oX8yknVsaah-ojQSThcEEIKUnSo9t5XvdYTBKDWY,3780
+patch/error_handler.py,sha256=8YK7z4aDj417pF3TyIwf9fRX2ldWdoER04EwD9-ZS7U,6453
+patch/exceptions.py,sha256=21y1rV6FPu7X8KfSPY691zh9nOXbpP-u-3QmbkVzfDs,1099
+patch/interpreter.py,sha256=qprHpqiOqC7imqeIceBL3uzAWm70fGs33HWCNe7vr5k,20298
+patch/objects.py,sha256=RNqWwY3pnBruWE3JQJnLOuT1Us1fWeoMWEIOh5INbZ8,24542
+patch/extensions/__init__.py,sha256=_wRFsm-XntEtqgDUnuOoro-GfXeuALdPlwQhAT7II2Y,232
+patch/extensions/mod/VecStim.mod,sha256=0NSBaol7vnQBTARDpyVK5orL_iPdypxWUIqloSYFUn8,2741
+nrn_patch-4.0.0.dist-info/entry_points.txt,sha256=1EWv69vzvdN9wt4upC_zWSiB2TSa-RP4Kc9rXslzzo8,52
+nrn_patch-4.0.0.dist-info/LICENSE,sha256=tJ_zaKC2tNV_HCEYSG7iwXiJjC_IYQpDiJYsgWkCMdI,1095
+nrn_patch-4.0.0.dist-info/WHEEL,sha256=Sgu64hAMa6g5FdzHxXv9Xdse9yxpGGMeagVtPMWpJQY,99
+nrn_patch-4.0.0.dist-info/METADATA,sha256=gUtgnxMATlLhAC3g2twj_2Gx9zwmRpAlAadKRhbnAPo,4339
+nrn_patch-4.0.0.dist-info/RECORD,,

nrn_patch-4.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: flit 3.9.0
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any

nrn_patch-4.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[glia.package]
+extensions=patch.extensions:package
+

patch/__init__.py

@@ -0,0 +1,65 @@
+"""
+Quality of life patch for the NEURON simulator.
+"""
+
+try:
+    from functools import cache, cached_property
+except ImportError:  # pragma: nocover
+    import functools
+
+    def cached_property(f):
+        return property(functools.lru_cache()(f))
+
+    functools.cache = cache = functools.lru_cache()
+    functools.cached_property = cached_property
+
+from .core import (
+    is_density_mechanism,
+    is_nrn_scalar,
+    is_point_process,
+    is_section,
+    is_segment,
+    transform,
+    transform_arc,
+    transform_netcon,
+    transform_record,
+)
+from .exceptions import NotConnectableError, NotConnectedError
+from .interpreter import PythonHocInterpreter
+
+__version__ = "4.0.0"
+p: "PythonHocInterpreter"
+h: "PythonHocInterpreter"
+
+
+def __getattr__(attr):
+    if attr == "p" or attr == "h":
+        return _get_interpreter()
+    else:
+        raise AttributeError(f"module {__name__} has no attribute {attr}.")
+
+
+@cache
+def _get_interpreter():
+    p = PythonHocInterpreter()
+    PythonHocInterpreter._process_registration_queue()
+    return p
+
+
+def connection(source, target, strict=True):
+    if not hasattr(source, "_connections"):
+        raise NotConnectableError(
+            f"Source {source} is not connectable. It lacks attribute _connections "
+            "required to form NetCons."
+        )
+    if not hasattr(target, "_connections"):
+        raise NotConnectableError(
+            f"Target {target} is not connectable. It lacks attribute _connections "
+            "required to form NetCons."
+        )
+    reverse = source in target._connections
+    if target not in source._connections:
+        if reverse and not strict:
+            return target._connections[source]
+        raise NotConnectedError("Source is not connected to target.")
+    return source._connections[target]

patch/core.py

@@ -0,0 +1,136 @@
+import typing
+from typing import Union
+
+from .exceptions import NotConnectableError
+
+if typing.TYPE_CHECKING:
+    from neuron.hoc import HocObject
+
+
+def transform(obj):
+    """
+    Transform an object to its NEURON representation, if the ``__neuron__`` magic
+    method is present.
+    """
+    if hasattr(obj, "__neuron__"):
+        return obj.__neuron__()
+    return obj
+
+
+def transform_netcon(obj):
+    """
+    Transform an object into the pointer that should be connected, if the ``__netcon__``
+    magic method is present.
+    """
+    if hasattr(obj, "__netcon__"):
+        return obj.__netcon__()
+    return transform(obj)
+
+
+def transform_record(obj):
+    """
+    Transform an object into the pointer that should be recorded, if the ``__record__``
+    magic method is present.
+    """
+    if hasattr(obj, "__record__"):
+        return obj.__record__()
+    return transform(obj)
+
+
+def transform_arc(obj, *args, **kwargs):
+    """
+    Get an arclength object on a NEURON object. Calls the ``__arc__`` magic method
+    on the callable object if present, otherwise returns the transformed object.
+    """
+    if hasattr(obj, "__arc__"):
+        return transform(obj(obj.__arc__(*args, **kwargs)))
+    else:
+        return transform(obj)
+
+
+def _is_sequence(obj):
+    t = type(obj)
+    return hasattr(t, "__len__") and hasattr(t, "__getitem__")
+
+
+def assert_connectable(obj, label=None):
+    """
+    Assert whether an object could be used as a :class:`~.objects.Connectable`.
+
+    :param label: Optional label to display to describe the object if the assertion fails.
+    :type label: str
+    """
+    if not hasattr(obj, "_connections"):
+        raise NotConnectableError(
+            (label if label is not None else str(obj))
+            + " is not connectable."
+            + "It lacks attribute `_connections` required to form NetCons."
+        )
+
+
+def is_section(obj):
+    """
+    Check if an object is a section.
+    """
+    cls = type(transform(obj))
+    return cls.__module__ == "nrn" and cls.__name__ == "Section"
+
+
+def is_segment(obj):
+    """
+    Check if an object is a segment.
+    """
+    cls = type(transform(obj))
+    return cls.__module__ == "nrn" and cls.__name__ == "Segment"
+
+
+def is_nrn_scalar(obj):
+    cls = type(transform(obj))
+    if cls.__module__ != "hoc" or cls.__name__ != "HocObject":
+        return False
+    try:
+        return "pointer to hoc scalar" in str(obj)
+    except Exception:
+        return False
+
+
+def is_point_process(obj: Union[str, "HocObject"]):
+    """
+    Check if obj is a (name of a) PointProcess on the ``HocInterpreter``.
+
+    :param obj: HocObject or name of the PointProcess to look for. Needs to be a known
+      attribute of ``neuron.h``.
+    :rtype: bool
+    """
+    from neuron import h, hoc
+
+    try:
+        if not isinstance(obj, hoc.HocObject):
+            obj = getattr(h, obj)
+    except Exception:
+        return False
+    return all(k in dir(obj) for k in ["get_loc", "has_loc", "loc", "get_segment"])
+
+
+def is_density_mechanism(obj: Union[str, "HocObject"]):
+    """
+    Check if obj is a (name of a) DensityMechanism on the ``HocInterpreter``.
+
+    :param obj: HocObject or name of the DensityMechanism to look for. Needs to be a known
+      attribute of ``neuron.h``.
+    :rtype: bool
+    """
+    import nrn
+    from neuron import h, hoc
+
+    if isinstance(obj, nrn.Mechanism):
+        return True
+    try:
+        if not isinstance(obj, hoc.HocObject):
+            obj = getattr(h, obj)
+        hname = str(obj)
+        return "neuron.DensityMechanism" in hname
+    except TypeError as e:
+        return "mechanism" in str(e)
+    except Exception as e:
+        return False

patch/error_handler.py

@@ -0,0 +1,188 @@
+import io
+import os
+import sys
+from contextlib import contextmanager
+
+from patch.exceptions import (
+    ErrorHandlingError,
+    HocConnectError,
+    HocError,
+    HocRecordError,
+    HocSectionAccessError,
+    PatchError,
+)
+
+
+@contextmanager
+def _suppress_nrn(stream=None, close=False):
+    """
+    Makes NEURON (mostly) shut the fuck up.
+    """
+    if stream is None:
+        stream = open(os.devnull, "w")
+        close = True
+    old_stdout = sys.stdout
+    old_stderr = sys.stderr
+    sys.stdout = stream
+    sys.stderr = stream
+    try:
+        yield
+    finally:
+        if close:
+            stream.close()
+        sys.stdout = old_stdout
+        sys.stderr = old_stderr
+
+
+@contextmanager
+def catch_hoc_error(*args, **context):
+    with io.StringIO() as error_stream:
+        try:
+            with _suppress_nrn(error_stream):
+                yield
+        except RuntimeError as e:
+            error = error_stream.getvalue()
+            try:
+                for handler in args:
+                    handler(error, context)
+            except Exception as e:
+                raise e from None
+            # Uncaught HocError
+            if "hoc error" in str(e) or "hocobj_call error" in str(e):
+                raise HocError(error) from None
+            # Actual RuntimeError
+            raise e from None  # pragma: nocover
+
+
+class ErrorHandler:
+    """
+    Base error handler class.
+
+    The class object is "callable" and takes the arguments that an error handle callable
+    should take. This means that when the class is passed in the argument list of
+    ``catch_hoc_error`` that we'll construct an object;
+
+    The constructor checks whether the context contains enough information for us to
+    handle the error and calls its ``catch`` method that you need to override. Inside of
+    the catch method you can analyze the error message and context and raise a polished
+    version of the error. All raised errors must inherit from ``patch.object.PatchError``
+    or they'll be treated as a failure of the error handler and an ``ErrorHandlingError``
+    will be raised on top of it.
+
+    To specify the required items of the context create a class attribute list
+    ``required``::
+
+      class A(ErrorHandler):
+          required = ["info_i_need_to_operate"]
+
+    Whenever the error handler class ``A`` is used, the ``catch_hoc_error`` call will
+    have the specify the keyword argument ``info_i_need_to_operate``.
+    """
+
+    def __init__(self, error, context):
+        if not hasattr(self.__class__, "required"):
+            raise ErrorHandlingError(
+                "Error context requirements missing for {}".format(
+                    self.__class__.__name__
+                )
+            )
+        for required_item in self.__class__.required:
+            if required_item not in context:
+                raise ErrorHandlingError(
+                    "Required error context item '{}' for {} is missing".format(
+                        required_item, self.__class__.__name__
+                    )
+                )
+        self.__dict__.update(context)
+        try:
+            self.catch(error, context)
+        except PatchError:
+            raise
+        except Exception as e:
+            raise ErrorHandlingError(
+                f"{self.__class__.__name__} errored out during error handling."
+            )
+
+    def catch(self, error, context):
+        raise ErrorHandlingError(
+            "Catch method not implemented for {}".format(self.__class__.__name__)
+        )
+
+
+def detector(error):
+    """
+    Pass this the error message and it returns a lambda function that you can pass a
+    string. Returns ``True`` if the string occurs in the error message, ``False``
+    otherwise.
+    """
+    return lambda trigger: error.lower().find(trigger) != -1
+
+
+class CatchNetCon(ErrorHandler):
+    """
+    Catches a variety of errors that can occur when using ``h.NetCon`` and raises
+    ``HocConnectError``.
+    """
+
+    required = ["nrn_source", "nrn_target"]
+
+    def catch(self, error, context):
+        e = detector(error)
+        if e("must be a point process or nullobject"):
+            if e("arg 1"):
+                raise HocConnectError(
+                    "Source is not a point process. Transformed type: '{}'".format(
+                        type(self.nrn_source)
+                    )
+                )
+            if e("arg 2"):
+                raise HocConnectError(
+                    "Target is not a point process. Transformed type: '{}'".format(
+                        type(self.nrn_target)
+                    )
+                )
+        if e("interpreter stack type error"):
+            raise HocConnectError(
+                "Incorrect types passed to NetCon. Source: {}, target: {}".format(
+                    type(self.nrn_source), type(self.nrn_target)
+                )
+            )
+
+
+# Section access errors can't be triggered without NEURON exiting:
+# https://github.com/neuronsimulator/nrn/issues/769
+class CatchSectionAccess(ErrorHandler):  #  pragma: nocover
+    """
+    Catches errors that occur when the Section stack is empty and accessed, raises
+    ``HocSectionAccessError``.
+    """
+
+    required = []
+
+    def catch(self, error, context):
+        e = detector(error)
+        if e("Section access unspecified"):
+            raise HocSectionAccessError(
+                "This operation requires a Section on the stack or perhaps a `sec` keyword argument."
+            )
+
+
+class CatchRecord(ErrorHandler):
+    """
+    Catches a variety of errors that occur when using ``h.Vector().record``, raises
+    ``HocRecordError``.
+    """
+
+    required = ["target"]
+
+    def catch(self, error, context):
+        e = detector(error)
+        if e("first arg is not a point_process") or e("interpreter stack type error"):
+            raise HocRecordError(
+                f"Can't record {self.target}, its record pointer is not a point process."
+            )
+        # Encountered this error locally, most likely on NEURON 7.7, don't cover
+        if e("number was provided instead of a pointer"):  #  pragma: nocover
+            raise HocRecordError(
+                f"Can't record {self.target}, its record pointer is a value. Make sure that you're recording `y._ref_x` rather than `y.x`."
+            )

patch/exceptions.py

@@ -0,0 +1,38 @@
+from typing import Type
+
+from errr.tree import exception as _e
+from errr.tree import make_tree as _make_tree
+
+_make_tree(
+    globals(),
+    PatchError=_e(
+        NotConnectableError=_e(),
+        NotConnectedError=_e(),
+        TransformError=_e(),
+        HocError=_e(
+            HocConnectError=_e(), HocRecordError=_e(), HocSectionAccessError=_e()
+        ),
+        SimulationError=_e(),
+        UninitializedError=_e(),
+        ErrorHandlingError=_e(),
+        ParallelError=_e(
+            ParallelConnectError=_e(),
+            BroadcastError=_e(),
+        ),
+    ),
+)
+
+PatchError: Type[Exception]
+NotConnectableError: Type[PatchError]
+NotConnectedError: Type[PatchError]
+TransformError: Type[PatchError]
+HocError: Type[PatchError]
+HocConnectError: Type[HocError]
+HocRecordError: Type[HocError]
+HocSectionAccessError: Type[HocError]
+SimulationError: Type[PatchError]
+UninitializedError: Type[PatchError]
+ErrorHandlingError: Type[PatchError]
+ParallelError: Type[PatchError]
+ParallelConnectError: Type[ParallelError]
+BroadcastError: Type[ParallelError]

patch/extensions/__init__.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+from glia import Mod, Package
+
+package = Package(
+    "patch_extensions",
+    Path(__file__).resolve().parent,
+    mods=[Mod("mod/VecStim.mod", "VecStim", variant="0", is_artificial_cell=True)],
+)