dendra 0.27.2__tar.gz

dendra-0.27.2/LICENSE.md

@@ -0,0 +1,39 @@
+This Agreement, effective as of the date the software is downloaded (“EFFECTIVE DATE”) is between Duke University ("DUKE"), a non-profit institution of higher education, and you (“YOU”), an individual accessing, downloading, or using the software.
+
+WHEREAS, DUKE owns and holds certain rights, title and interest to copyrighted software pertaining to OTC File T-008477 (“PROGRAM”); and
+
+WHEREAS, DUKE owns and holds certain rights, title, and interest to the following patent application/issued patent (PATENT APPLICATION NO. 18/182,018)  for the technology described in OTC File T-007793 (“PATENT RIGHTS"); and
+
+WHEREAS, DUKE desires to distribute the PROGRAM for academic, non-commercial research use and testing, and to promote marketing and commercialization of the PATENT RIGHTS, DUKE herein agrees to grant a limited license to the PROGRAM for research, non-commercial purposes only, with DUKE retaining all other rights and uses to both the PATENT RIGHTS and the PROGRAM;
+
+THEREFORE, DUKE hereby agrees to make the PROGRAM available to YOU, subject to the following terms and conditions:
+
+1.  Grant.
+
+    (a) Subject to the terms of this Agreement, DUKE hereby grants YOU a royalty-free, non-transferable, non-exclusive, worldwide license under its copyright to use, reproduce, modify, publicly display, and perform the PROGRAM solely for non-commercial research and/or academic testing purposes.
+
+    (b) In order to obtain any further license rights, including the right to use the PROGRAM, any modifications or derivatives made by YOU, and/or PATENT RIGHTS for commercial purposes, (including using modifications as part of an industrially sponsored research project), YOU must contact DUKE’s Office for Translation and Commercialization (Digital Innovations Team) about additional commercial license agreements.
+
+2.  Disclaimer.   THE PROGRAM MADE AVAILABLE HEREUNDER IS "AS IS", WITHOUT WARRANTY OF ANY KIND EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, NOR REPRESENTATION THAT THE PROGRAM DOES NOT INFRINGE THE INTELLECTUAL PROPERTY RIGHTS OF ANY THIRD PARTY. DUKE has no obligation to assist in your installation or use of the PROGRAM or to provide services or maintenance of any type with respect to the PROGRAM.  The entire risk as to the quality and performance of the PROGRAM is borne by YOU.  YOU acknowledge that the PROGRAM may contain errors or bugs. YOU must determine whether the PROGRAM sufficiently meets your requirements.  This disclaimer of warranty constitutes an essential part of this Agreement.
+
+3. No Consequential Damages; Indemnification.  IN NO EVENT SHALL DUKE BE LIABLE TO YOU FOR ANY LOST PROFITS OR OTHER DIRECT, INDIRECT, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL DAMAGES RELATING TO THE SUBJECT MATTER OF THIS AGREEMENT.
+
+4. Copyright.  YOU agree to retain DUKE’S copyright notice: “Copyright 2024 Duke University. All Rights Reserved” on all copies of the PROGRAM or portions thereof.
+
+5.  Term and Termination.    The Term of this Agreement shall be five (5) years from the date YOU accept the terms of this license.  If YOU at any time fail to abide by the terms of this Agreement, DUKE shall have the right to immediately terminate the license granted herein, require the return or destruction of all copies of the PROGRAM from YOU, and obtain certification in writing as to such return or destruction, and pursue any other legal or equitable remedies available.
+
+6. Export Control.   YOU agree to comply with all United States export control laws and regulations controlling the export of the PROGRAM, including, without limitation, all Export Administration Regulations of the United States Department of Commerce.  Among other things, these laws and regulations prohibit, or require a license for, the export of certain types of software to specified countries.
+
+7. Notices or Additional Licenses.  Any notice, communication or commercial license requests shall be directed to:
+
+    Duke University\
+    Office for Translation and Commercialization\
+    Physical Address: 2812 Erwin Rd #406, Durham, NC 27705\
+    Mailing Address: PO Box 90083, Durham, NC 27708\
+    ATTENTION: Daniel Dardani, Director of Physical Sciences and Digital Innovations Licensing daniel.dardani@duke.edu
+
+
+
+8.  General.  This Agreement shall be governed by the laws of the State of North Carolina.  The parties acknowledge that this Agreement sets forth the entire Agreement and understanding of the parties as to the subject matter.
+
+PROCEEDING WITH DOWNLOADING / FORKING / CLONING THE SOFTWARE CONSTITUTES ACCEPTANCE OF THIS AGREEMENT.  YOU ARE CONSENTING TO BE BOUND BY ALL OF THE TERMS OF THIS AGREEMENT.  IF YOU DO NOT AGREE TO ALL THE TERMS OF THIS AGREEMENT DISCONTINUE THE INSTALLATION / CLONING / FORKING / DOWNLOAD PROCESS.

dendra-0.27.2/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: dendra
+Version: 0.27.2
+Summary: Differentiable neuronal simulation and macroscopic descriptor optimization
+License-Expression: LicenseRef-Duke-Research-NonCommercial
+Project-URL: Documentation, https://wmglab-duke.github.io/dendra/
+Project-URL: Repository, https://github.com/wmglab-duke/dendra
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: numpy
+Requires-Dist: sympy>=1.2
+Requires-Dist: torch>=2.12.0
+Requires-Dist: scipy
+Requires-Dist: h5py
+Requires-Dist: tqdm
+Requires-Dist: natsort
+Requires-Dist: dask
+Requires-Dist: networkx
+Requires-Dist: pandas
+Requires-Dist: neuron
+Requires-Dist: matplotlib
+Requires-Dist: ninja
+Provides-Extra: solvers
+Requires-Dist: dendra-solvers>=0.3.1; extra == "solvers"
+Provides-Extra: jupyter
+Requires-Dist: ipympl>=0.9.5; extra == "jupyter"
+Provides-Extra: doc
+Requires-Dist: jupyter_contrib_nbextensions; extra == "doc"
+Requires-Dist: notebook<=6.4.12; extra == "doc"
+Requires-Dist: traitlets<=5.9.0; extra == "doc"
+Requires-Dist: ipython<=8.9.0; extra == "doc"
+Requires-Dist: mkdocs; extra == "doc"
+Requires-Dist: mkdocs-material; extra == "doc"
+Requires-Dist: markdown-include; extra == "doc"
+Requires-Dist: mkdocs-redirects; extra == "doc"
+Requires-Dist: mkdocstrings[python]>=0.18; extra == "doc"
+Requires-Dist: mike; extra == "doc"
+Requires-Dist: sphinx; extra == "doc"
+Requires-Dist: sphinx-autobuild; extra == "doc"
+Requires-Dist: sphinx_autodoc_typehints; extra == "doc"
+Requires-Dist: sphinx-math-dollar; extra == "doc"
+Requires-Dist: myst-nb; extra == "doc"
+Requires-Dist: jupytext; extra == "doc"
+Requires-Dist: shibuya; extra == "doc"
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: commitizen; extra == "dev"
+Dynamic: license-file
+Dynamic: requires-dist
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/wmglab-duke/dendra/main/docs/_static/logo-light.png" alt="Dendra">
+</div>
+
+***
+
+[![PyTorch](https://img.shields.io/badge/PyTorch-%23EE4C2C.svg?style-plastic&logo=PyTorch&logoColor=white)](https://pytorch.org/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![Code style: Ruff](https://img.shields.io/badge/code%20style-Ruff-D7FF64.svg?logo=ruff&logoColor=261230)](https://docs.astral.sh/ruff/)
+
+Dendra is a differentiable biophysical neuron and network simulator built on
+PyTorch. It supports CPU and GPU execution, extracellular fields, event-based
+networks, and macroscopic descriptors for gradient-based model training.
+
+## Documentation
+
+The complete documentation is published at
+[wmglab-duke.github.io/dendra](https://wmglab-duke.github.io/dendra/). Start
+with the [installation guide](https://wmglab-duke.github.io/dendra/installation.html),
+then see the tutorials and the
+[unit conventions](https://wmglab-duke.github.io/dendra/units.html).
+
+## Installation
+
+Dendra requires Python 3.11 or newer and PyTorch 2.12 or newer. On Windows,
+install inside WSL2 because the required NEURON dependency does not publish
+native Windows wheels on PyPI.
+
+Install Dendra with the recommended native CPU solvers:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install --only-binary=dendra-solvers "dendra[solvers]"
+```
+
+The `solvers` extra installs
+[`dendra-solvers`](https://pypi.org/project/dendra-solvers/), which provides
+native CPU solvers for block and tree models. If a compatible solver wheel is
+unavailable, install the base package:
+
+```bash
+python -m pip install dendra
+```
+
+The base package retains Dendra's PyTorch CPU solver for unbranched cables and
+all GPU solvers. To select a particular CPU, CUDA, or ROCm build, install
+PyTorch first using its
+[installation selector](https://pytorch.org/get-started/locally/), then install
+Dendra.
+
+For interactive Matplotlib figures in Jupyter, install the Jupyter extra:
+
+```bash
+python -m pip install "dendra[jupyter]"
+```
+
+Verify the installed dependencies and inspect the deployment environment:
+
+```bash
+python -m pip check
+python -m dendra doctor
+```
+
+The [installation guide](https://wmglab-duke.github.io/dendra/installation.html)
+explains solver-wheel support, source installations, upgrades, and Jupyter
+setup. For CUDA deployment checks, see the
+[GPU deployment guide](https://wmglab-duke.github.io/dendra/gpu-deployment.html).
+
+## Development
+
+The [contribution guide](https://github.com/wmglab-duke/dendra/blob/main/CONTRIBUTING.md)
+describes development setup and the GitHub pull-request workflow. The
+[testing and code coverage guide](https://wmglab-duke.github.io/dendra/testing.html)
+covers the CPU, NEURON, CUDA, sanitizer, and coverage lanes.
+
+## Citation
+
+A citation for Dendra and its accompanying manuscript will be added when it is
+available. Please also consider citing the work where geometric and topological
+surrogates and gradient-based design of selective neurostimulation are
+discussed in detail:
+
+Minhaj A. Hussain, Warren M. Grill, Nicole A. Pelot. "Highly efficient
+modeling and optimization of neural fiber responses to electrical
+stimulation." *Nature Communications.* 2024.
+[doi:10.1038/s41467-024-51709-8](https://doi.org/10.1038/s41467-024-51709-8)
+
+```bibtex
+@article{hussain_highly_2024,
+    title = {Highly efficient modeling and optimization of neural fiber responses to electrical stimulation},
+    doi = {10.1038/s41467-024-51709-8},
+    journal = {Nature Communications},
+    author = {Hussain, Minhaj A. and Grill, Warren M. and Pelot, Nicole A.},
+    year = {2024}
+}
+```
+
+## License
+
+Dendra is distributed under Duke University's custom license for non-commercial
+research and academic testing. Commercial use, including industrially
+sponsored research, requires a separate agreement with Duke's Office for
+Translation and Commercialization. The
+[license](https://github.com/wmglab-duke/dendra/blob/main/LICENSE.md) governs
+all use; downloading, cloning, or forking the software constitutes acceptance
+of those terms.

dendra-0.27.2/README.md

@@ -0,0 +1,106 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/wmglab-duke/dendra/main/docs/_static/logo-light.png" alt="Dendra">
+</div>
+
+***
+
+[![PyTorch](https://img.shields.io/badge/PyTorch-%23EE4C2C.svg?style-plastic&logo=PyTorch&logoColor=white)](https://pytorch.org/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![Code style: Ruff](https://img.shields.io/badge/code%20style-Ruff-D7FF64.svg?logo=ruff&logoColor=261230)](https://docs.astral.sh/ruff/)
+
+Dendra is a differentiable biophysical neuron and network simulator built on
+PyTorch. It supports CPU and GPU execution, extracellular fields, event-based
+networks, and macroscopic descriptors for gradient-based model training.
+
+## Documentation
+
+The complete documentation is published at
+[wmglab-duke.github.io/dendra](https://wmglab-duke.github.io/dendra/). Start
+with the [installation guide](https://wmglab-duke.github.io/dendra/installation.html),
+then see the tutorials and the
+[unit conventions](https://wmglab-duke.github.io/dendra/units.html).
+
+## Installation
+
+Dendra requires Python 3.11 or newer and PyTorch 2.12 or newer. On Windows,
+install inside WSL2 because the required NEURON dependency does not publish
+native Windows wheels on PyPI.
+
+Install Dendra with the recommended native CPU solvers:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install --only-binary=dendra-solvers "dendra[solvers]"
+```
+
+The `solvers` extra installs
+[`dendra-solvers`](https://pypi.org/project/dendra-solvers/), which provides
+native CPU solvers for block and tree models. If a compatible solver wheel is
+unavailable, install the base package:
+
+```bash
+python -m pip install dendra
+```
+
+The base package retains Dendra's PyTorch CPU solver for unbranched cables and
+all GPU solvers. To select a particular CPU, CUDA, or ROCm build, install
+PyTorch first using its
+[installation selector](https://pytorch.org/get-started/locally/), then install
+Dendra.
+
+For interactive Matplotlib figures in Jupyter, install the Jupyter extra:
+
+```bash
+python -m pip install "dendra[jupyter]"
+```
+
+Verify the installed dependencies and inspect the deployment environment:
+
+```bash
+python -m pip check
+python -m dendra doctor
+```
+
+The [installation guide](https://wmglab-duke.github.io/dendra/installation.html)
+explains solver-wheel support, source installations, upgrades, and Jupyter
+setup. For CUDA deployment checks, see the
+[GPU deployment guide](https://wmglab-duke.github.io/dendra/gpu-deployment.html).
+
+## Development
+
+The [contribution guide](https://github.com/wmglab-duke/dendra/blob/main/CONTRIBUTING.md)
+describes development setup and the GitHub pull-request workflow. The
+[testing and code coverage guide](https://wmglab-duke.github.io/dendra/testing.html)
+covers the CPU, NEURON, CUDA, sanitizer, and coverage lanes.
+
+## Citation
+
+A citation for Dendra and its accompanying manuscript will be added when it is
+available. Please also consider citing the work where geometric and topological
+surrogates and gradient-based design of selective neurostimulation are
+discussed in detail:
+
+Minhaj A. Hussain, Warren M. Grill, Nicole A. Pelot. "Highly efficient
+modeling and optimization of neural fiber responses to electrical
+stimulation." *Nature Communications.* 2024.
+[doi:10.1038/s41467-024-51709-8](https://doi.org/10.1038/s41467-024-51709-8)
+
+```bibtex
+@article{hussain_highly_2024,
+    title = {Highly efficient modeling and optimization of neural fiber responses to electrical stimulation},
+    doi = {10.1038/s41467-024-51709-8},
+    journal = {Nature Communications},
+    author = {Hussain, Minhaj A. and Grill, Warren M. and Pelot, Nicole A.},
+    year = {2024}
+}
+```
+
+## License
+
+Dendra is distributed under Duke University's custom license for non-commercial
+research and academic testing. Commercial use, including industrially
+sponsored research, requires a separate agreement with Duke's Office for
+Translation and Commercialization. The
+[license](https://github.com/wmglab-duke/dendra/blob/main/LICENSE.md) governs
+all use; downloading, cloning, or forking the software constitutes acceptance
+of those terms.

dendra-0.27.2/dendra/__init__.py

@@ -0,0 +1,257 @@
+"""Dendra: A PyTorch-based framework for simulating and modeling neural dynamics."""
+
+import os
+
+__version__ = "0.27.2"
+
+os.environ.setdefault("OMP_DYNAMIC", "FALSE")
+os.environ.setdefault("MKL_DYNAMIC", "FALSE")
+os.environ["OMP_PROC_BIND"] = "true"
+os.environ["OMP_PLACES"] = "cores"
+
+from ._bootstrap import (
+    _should_cache_cpu_isa_for_dendra,
+    _should_configure_torchinductor_cache_on_import,
+    configure_torchinductor_cache_for_dendra,
+)
+
+_torchinductor_cache_opt_in = _should_configure_torchinductor_cache_on_import()
+if _torchinductor_cache_opt_in:
+    configure_torchinductor_cache_for_dendra()
+
+import pickle
+import time
+import warnings
+from pathlib import Path
+
+import torch
+
+import dendra.func as func
+import dendra.models.callbacks as callbacks
+import dendra.models.mod as mod
+
+from .const import FARADAY, PI, TAU, E, R
+from .diagnostics import doctor
+from .helpers import (
+    COMPILE_OPTIONS,
+    DEVICE,
+    DTYPE,
+    NATIVE_EXTENSION_POLICY,
+    PRESERVE_MECHANISM_POPULATION_AXIS,
+    RUNTIME_CONTRACT_VALIDATION,
+    TF32,
+    allow_tf32,
+    ctx,
+    current_compile_options,
+    current_device,
+    current_dtype,
+    current_native_extension_policy,
+    current_preserve_mechanism_population_axis,
+    current_runtime_contract_validation,
+    normalize_native_extension_policy,
+    normalize_preserve_mechanism_population_axis,
+    normalize_runtime_contract_validation,
+    set_compile_options,
+    set_jit_enabled,
+    set_jit_in_network_enabled,
+    set_jit_network_ops_enabled,
+    set_jit_network_solves_enabled,
+)
+from .models import (
+    Axon,
+    Cable,
+    CompartmentGeometry,
+    CompartmentGraph,
+    CompartmentMetadata,
+    CompartmentTopology,
+    DistributionSpec,
+    ExtCellAxon,
+    ExtCellTree,
+    Morphology,
+    Myelinated,
+    NetStim,
+    Network,
+    Population,
+    RandomParameterSpec,
+    RuntimeNoiseSpec,
+    Section,
+    SectionLocation,
+    SingleCompartment,
+    SynapseSlots,
+    Tree,
+    Unmyelinated,
+    available_random_distributions,
+    concat_models,
+    concat_slices,
+    connect_morphologies,
+    get_random_distribution,
+    insert_intrinsic_activity,
+    make_random_parameter_spec,
+    make_runtime_noise_spec,
+    passive_end_nodes_,
+    register_random_distribution,
+    remove_intrinsic_activity,
+    sample_random_parameter,
+    sample_runtime_noise,
+)
+from .models.fields import *
+from .models.integrators import (
+    bwd_euler_bt,
+    bwd_euler_sc,
+    bwd_euler_ub,
+    df,
+    dfh,
+    dhs,
+    dufort_frankel,
+    dufort_frankel_homogeneous,
+    euler,
+    eulerv1,
+    rk1,
+    rk2,
+    rk4,
+    scnv,
+)
+from .models.mod import load_mechanisms
+from .models.stim.waveform import *
+from .stepping import step, step_network, step_population
+
+__all__ = [
+    "PI",
+    "E",
+    "TAU",
+    "R",
+    "FARADAY",
+    "ctx",
+    "doctor",
+    "step",
+    "step_population",
+    "step_network",
+    "DEVICE",
+    "DTYPE",
+    "NATIVE_EXTENSION_POLICY",
+    "PRESERVE_MECHANISM_POPULATION_AXIS",
+    "RUNTIME_CONTRACT_VALIDATION",
+    "COMPILE_OPTIONS",
+    "current_compile_options",
+    "current_device",
+    "current_dtype",
+    "current_native_extension_policy",
+    "current_preserve_mechanism_population_axis",
+    "current_runtime_contract_validation",
+    "normalize_runtime_contract_validation",
+    "normalize_native_extension_policy",
+    "normalize_preserve_mechanism_population_axis",
+    "set_compile_options",
+    "set_jit_enabled",
+    "set_jit_network_solves_enabled",
+    "set_jit_network_ops_enabled",
+    "set_jit_in_network_enabled",
+    "callbacks",
+    "func",
+    "mod",
+    "load_mechanisms",
+    "DistributionSpec",
+    "RandomParameterSpec",
+    "RuntimeNoiseSpec",
+    "available_random_distributions",
+    "get_random_distribution",
+    "register_random_distribution",
+    "make_random_parameter_spec",
+    "make_runtime_noise_spec",
+    "sample_random_parameter",
+    "sample_runtime_noise",
+    "insert_intrinsic_activity",
+    "remove_intrinsic_activity",
+    "passive_end_nodes_",
+    "Population",
+    "Morphology",
+    "Section",
+    "SectionLocation",
+    "CompartmentTopology",
+    "CompartmentGeometry",
+    "CompartmentMetadata",
+    "CompartmentGraph",
+    "SingleCompartment",
+    "Cable",
+    "Axon",
+    "Unmyelinated",
+    "Myelinated",
+    "Tree",
+    "ExtCellAxon",
+    "ExtCellTree",
+    "NetStim",
+    "Network",
+    "SynapseSlots",
+    "concat_models",
+    "concat_slices",
+    "connect_morphologies",
+    "anisotropic_point",
+    "isotropic_point",
+    "parametric_efield",
+    "PreComputedInterpolate1D",
+    "precomputed_interpolate_1d",
+    "EfieldInterpolate3DRect",
+    "efield_interpolate_3d_rect",
+    "PreComputedInterpolate3DRect",
+    "precomputed_interpolate_3d_rect",
+    "PreComputedInterpolate3DScattered",
+    "precomputed_interpolate_3d_scattered",
+    "EfieldInterpolate3DScattered",
+    "efield_interpolate_3d_scattered",
+    "euler",
+    "eulerv1",
+    "rk1",
+    "rk2",
+    "rk4",
+    "dufort_frankel",
+    "dufort_frankel_homogeneous",
+    "bwd_euler_sc",
+    "bwd_euler_ub",
+    "bwd_euler_bt",
+    "dhs",
+    "df",
+    "dfh",
+    "scnv",
+]
+
+
+def _cache_cpu_isa_list():
+    """
+    Checks for a cached CPU ISA string. If not found, runs the slow
+    detection and caches the result for future runs.
+    """
+    # Use a standard cache location.
+    cache_dir = Path.home() / ".cache" / "dendra"
+    cache_file = cache_dir / f"cpu_isa_list_{torch.__version__}"
+
+    def get_valid_vec_isa_list():
+        with open(cache_file, "rb") as f:
+            return pickle.load(f)
+
+    # --- Cache Hit ---
+    if cache_file.exists():
+        # Check if the PyTorch version matches the one used to create the cache.
+        torch._inductor.cpu_vec_isa.valid_vec_isa_list = get_valid_vec_isa_list
+        return
+
+    # --- Cache Miss or Stale Cache ---
+    print("Dendra: Performing one-time CPU capability check. This may take a minute...")
+    try:
+        os.makedirs(cache_dir, exist_ok=True)
+        start = time.time()
+        valid_vec_isa_list = torch._inductor.cpu_vec_isa.valid_vec_isa_list()
+        print(f"Dendra: CPU capability check took {(time.time() - start):.3f}s.")
+        with open(cache_file, "wb") as f:
+            pickle.dump(valid_vec_isa_list, f)
+    except Exception as e:
+        warnings.warn(
+            f"Dendra: CPU capability check failed: {e}. Falling back to default behavior."
+        )
+        return
+
+
+if _torchinductor_cache_opt_in and _should_cache_cpu_isa_for_dendra():
+    _cache_cpu_isa_list()
+
+# setup environment
+allow_tf32(bool(TF32))

dendra-0.27.2/dendra/__main__.py

@@ -0,0 +1,5 @@
+"""Run Dendra's command-line interface with ``python -m dendra``."""
+
+from .cli import main
+
+raise SystemExit(main())