Development -> Master

.agents/2026-04-22.md

@@ -0,0 +1,32 @@
+# Session: 2026-04-22
+
+**Authoring agent:** opencode
+
+## Objective
+Implemented `NmlPythonizer` — converts NeuroML XML files into Python scripts using the libNeuroML API.
+
+## Completed
+- Created `pyneuroml/utils/nml2py.py` with `NmlPythonizer` class
+- Traverses object tree via `info()`, generates `parent.add()` calls with string-literal references
+- Extracts inline cells/channels/synapses to separate files; preserves includes
+- Orders output by human-logical construction: networks -> populations -> cells -> channels -> synapses -> projections -> connections -> inputs -> metadata
+- Type classification uses substring matching (`"Cell" in type_name`) rather than hardcoded sets to avoid maintenance drift
+- All NmlId and population references kept as string literals (XML paths like `cell/0/soma/3` cannot be reliably resolved)
+- Verified round-trip: generated script produces model identical to original XML
+
+## Key Design Decisions
+- Root doc via `component_factory()`, all others via `parent.add()`
+- Variable names from component `id` attributes; type-based names with counters for idless components
+- `_is_default_value()` compares against fresh instance defaults to skip cluttering output
+
+## Lessons Learned
+- `read_neuroml2_file` (not `read_neuroml2`) is the correct import from `pyneuroml.io`
+- `Connection.id` can be an integer — `_sanitize_var_name` must handle both
+- Some attributes have non-None defaults (e.g., `Connection.pre_segment_id = 0`) — must compare against defaults, not just `None`
+
+## Open Questions
+- Future: handle cell XML files with morphologies (currently skipped due to size)
+
+## References
+- [libNeuroML generatedssupersuper.py](https://github.com/NeuralEnsemble/libNeuroML/blob/master/neuroml/nml/generatedssupersuper.py) - `add()`, `component_factory()`, `info()` implementation
+- [Test XML](https://github.com/NeuroML/Documentation/raw/refs/heads/main/source/Userdocs/NML2_examples/izhikevich2007_network.nml) - 2 populations, 20 connections, 5 pulse generators

.agents/2026-04-29.md

@@ -0,0 +1,16 @@
+# Session: 2026-04-29
+
+**Authoring agent:** opencode
+
+## Objective
+Reviewed include path handling in `nml2py.py` and discussed round-trip test strategy.
+
+## Completed
+- Decided to keep original include hrefs as-is (no `../` prefix) with a user note explaining they may need to update paths or copy files
+
+## Open Questions
+- Round-trip test design: `info()` dict comparison is closest option, but must account for different include paths and extracted inline components. Need to compare children by type+id rather than position. Deeper discussion deferred.
+
+## Notes
+- Branch: `feat-xml2py`
+- Latest commit: `9e86aff` (feat: add nml2py entry point)

.agents/2026-05-12.md

@@ -0,0 +1,19 @@
+# Session: 2026-05-12
+
+**Authoring agent:** opencode
+
+## Objective
+Diagnosed pytest logging capture issues and added tests for nml2py.py generator methods.
+
+## Completed
+- Identified root cause: `--log-cli-level` doesn't work with xdist; `--log-level=DEBUG` captures logs but hides them for passing tests (need `-rP`)
+- Updated AGENTS.md with logging quirks and "be concise" convention
+- Added `test_generated_code_structure` (string assertions) and `test_generated_code_exec` (exec + namespace) for nml2py.py
+- Removed `_is_default_value` from nml2py.py — now always includes all values explicitly
+
+## Errors and Lessons
+- `tests/lems/` directory shadows real `lems` package in sys.path when cwd is `tests/` — caused confusing import errors
+- `pyneuroml` and `tests.*` loggers are in different branches of the logger hierarchy; `propagate=False` on pyneuroml has no effect on test loggers
+
+## References
+- AGENTS.md for full pytest logging quirks

.agents/Readme.md

@@ -0,0 +1,46 @@
+# Agent Session Summaries
+
+Directory for storing summaries from chats with coding agents for future context.
+
+## Session File Format
+
+Based on Claude Code's session memory structure.
+
+```markdown
+# Session: YYYY-MM-DD
+
+**Authoring agent:** <agent-name>
+
+## Objective
+Brief 1-2 sentence overview of what was discussed/accomplished.
+
+## Completed
+- Completed item 1
+- Completed item 2
+
+## Errors and Lessons
+- Lesson learned (from error)
+
+## Open Questions
+- Question 1
+
+## Notes
+Any other relevant context for future agents
+
+## References
+- [Title](URL) - brief description
+```
+
+## Naming Convention
+
+Session files should be named with the date:
+```
+YYYY-MM-DD.md
+```
+
+## Guidelines
+
+- **Be concise**: Logs are added to agent context. Aim for 5-10 lines total. Focus on decisions and outcomes, not task-by-task details.
+- **Focus on continuity**: Capture what's needed to continue work in future sessions.
+- **Omit routine work**: Don't log every lint fix or commit unless noteworthy.
+- **Preserve information**: When updating a session log, do not remove existing content. Merge new information with what's already there.

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
       fail-fast: false
 
     steps:
@@ -36,15 +36,16 @@ jobs:
         echo "github.ref is: ${{ github.ref }}"
         echo "github.base_ref is: ${{ github.base_ref }}"
 
+
     - name: Upgrade pip, install deps
       run: |
         python -m pip install --upgrade pip
-        pip install 'numpy<2.0.0' # due to lingering issues with other modules
         pip install .[dev]
 
     - name: List packages so far
       run: |
         pip list
+        env
 
     - name: Run tests
       run: |

.gitignore

@@ -138,7 +138,7 @@ examples/results/*.dat
 .mypy_cache/
 /examples/test_data/TwoCell.net.png
 /examples/test_data/Purk2M9s.png
-/.coverage
+**/.coverage
 /Nav.channel.nml
 /iv_izh2007RS0.net.nml
 /leak_chan.channel.nml
@@ -181,3 +181,10 @@ coverage.xml
 /examples/hhcell.swc
 /examples/metadata.rdf
 /tests/utils/test_translation.net.nml
+/examples/LEMS_NML2_Ex5_DetCell.neux.zip
+/examples/NML2_SingleCompHHCell.neux.zip
+/tests/HH_example.neux.zip
+
+.opencode/
+
+/tests/temp_nml2py*

.pre-commit-config.yaml

@@ -2,13 +2,14 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v6.0.0
     hooks:
-    -   id: trailing-whitespace
-    -   id: end-of-file-fixer
-    -   id: check-added-large-files
+    - id: trailing-whitespace
+    - id: end-of-file-fixer
+    - id: check-added-large-files
+      args: [ "--maxkb=5000"]
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.4.1
+  rev: v0.15.12
   hooks:
     - id: ruff
       args: [ "--select", "I", "--fix" ]

AGENTS.md

@@ -0,0 +1,74 @@
+# AGENTS.md - pyNeuroML
+
+Single Python package for reading, writing, simulating and analysing NeuroML2/LEMS models.
+
+## Architecture
+
+- **Single package** — all code under `pyneuroml/`, tests under `tests/`, examples under `examples/`
+- **Bundled jNeuroML** — `pyneuroml/lib/*.jar` provides Java simulation backend
+- **CLI entry points** — `pynml` (main), `jnml`, `pynml-channelanalysis`, `pynml-povray`, `pynml-tune`, `pynml-swc2nml`, `pynml-xpp`, and others (see `setup.cfg` `[options.entry_points]`)
+- **Core modules**: `pynml.py` (main CLI), `io.py`, `runners.py`, `lems/`, `analysis/`, `neuron/`, `channelml/`, `plot/`, `tune/`, `swc/`, `xppaut/`
+
+## Developer Commands
+
+```bash
+# Install for development (from repo root)
+pip install .[dev]
+
+# Run lint + format (ruff)
+ruff check . --fix
+ruff format .
+
+# Run full test suite (installs deps, runs CLI tests + pytest + examples)
+./test.sh             # or ./test-ghactions.sh
+./test-ghactions.sh -neuron   # includes NEURON examples
+
+# Run pytest only (skips tests marked localonly — they segfault on CI)
+pytest -m "not localonly"
+
+# Run a single test file
+pytest tests/test_pynml.py
+
+# Run pre-commit hooks manually
+pre-commit run --all-files
+```
+
+## Testing Quirks
+
+- `pyproject.toml` defines a `localonly` marker — tests with it are skipped on GitHub Actions because they segfault
+- `test-ghactions.sh` is the authoritative test script; it installs the package, verifies all CLI tools, runs pytest, and executes examples
+- Some tests require a display (matplotlib); they're guarded by `if [[ "$CI" != "true" ]]`
+- NEURON examples require the `-neuron` flag and `nrniv` on PATH
+- **Pytest logging**: `--log-level=DEBUG` captures logs but hides them for passing tests by default — use `-rP` to show. `--log-cli-level` does not work with xdist.
+
+## CI
+
+- **ci.yml** — matrix build on Python 3.9–3.13, runs `./test-ghactions.sh -neuron`
+- **ruff.yml** — ruff check on PRs (changed files only)
+- **python-publish.yml** — PyPI publishing
+
+## Conventions
+
+- **Be concise**: no fluff, no explanations, no summaries of what was done — just the answer.
+- **No unicode characters in code**: use ASCII only in comments and strings.
+- **Branch**: development is the working branch; master is stable
+- **Ruff config**: ignores `F403`, `F405` (wildcard imports); excludes `examples/`
+- **mypy**: `ignore_missing_imports = True` (minimal type checking)
+- **Pre-commit**: trailing whitespace, EOF fixer, large file check (<5MB), ruff import sort + format
+- **Python support**: 3.9–3.13
+
+## Session Continuity
+
+- Check `.agents/` for prior session logs (`YYYY-MM-DD.md`) at session start
+- Use the template in `.agents/Readme.md` for new session summaries
+
+## Dependencies
+
+- **External**: Java (JRE) for jNeuroML, Graphviz (`dot`) for diagrams
+- **Optional backends**: NEURON, Brian2, NetPyNE, Tellurium (installed via extras like `[neuron]`, `[brian]`, etc.)
+
+## References
+
+- `setup.cfg` — authoritative source for entry points, extras, and dependencies
+- `pyproject.toml` — pytest, ruff, and coverage config
+- `test-ghactions.sh` — full integration test flow

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

LICENSE.lesser

@@ -163,4 +163,3 @@ whether future versions of the GNU Lesser General Public License shall
 apply, that proxy's public statement of acceptance of any version is
 permanent authorization for you to choose that version for the
 Library.
-

README.md

@@ -21,7 +21,7 @@ A single package in Python unifying scripts and modules for reading, writing, si
 
 Builds on: [libNeuroML](https://github.com/NeuralEnsemble/libNeuroML) & [PyLEMS](https://github.com/LEMS/pylems) and wraps functionality from [jNeuroML](https://github.com/NeuroML/jNeuroML).
 
-Installation
+Installation 
 ------------
 
 ### Dependencies

docs/source/pyneuroml.analysis.rst

@@ -29,4 +29,3 @@ pyneuroml.analysis.ChannelHelper module
    :members:
    :undoc-members:
    :show-inheritance:
-

docs/source/pyneuroml.channelml.rst

@@ -5,4 +5,3 @@ pyneuroml.channelml package
    :members:
    :undoc-members:
    :show-inheritance:
-

docs/source/pyneuroml.neuron.rst

@@ -13,4 +13,3 @@ pyneuroml.neuron.analysis module
    :members:
    :undoc-members:
    :show-inheritance:
-

docs/source/pyneuroml.povray.rst

@@ -29,4 +29,3 @@ pyneuroml.povray.OverlaySimulation module
    :members:
    :undoc-members:
    :show-inheritance:
-

docs/source/pyneuroml.swc.rst

@@ -21,3 +21,11 @@ pyneuroml.swc.ExportSWC module
    :members:
    :undoc-members:
    :show-inheritance:
+
+pyneuroml.swc.ExportNML module
+------------------------------
+
+.. automodule:: pyneuroml.swc.ExportNML
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/pyneuroml.utils.rst

@@ -6,18 +6,26 @@ pyneuroml.utils package
    :undoc-members:
    :show-inheritance:
 
-pyneuroml.utils.info module
+pyneuroml.utils.cli module
 ---------------------------
 
-.. automodule:: pyneuroml.utils.info
+.. automodule:: pyneuroml.utils.cli
    :members:
    :undoc-members:
    :show-inheritance:
 
-pyneuroml.utils.plot module
+pyneuroml.utils.components module
+----------------------------------
+
+.. automodule:: pyneuroml.utils.components
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pyneuroml.utils.info module
 ---------------------------
 
-.. automodule:: pyneuroml.utils.plot
+.. automodule:: pyneuroml.utils.info
    :members:
    :undoc-members:
    :show-inheritance:
@@ -30,10 +38,18 @@ pyneuroml.utils.misc module
    :undoc-members:
    :show-inheritance:
 
-pyneuroml.utils.cli module
+pyneuroml.utils.plot module
 ---------------------------
 
-.. automodule:: pyneuroml.utils.cli
+.. automodule:: pyneuroml.utils.plot
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pyneuroml.utils.simdata module
+-------------------------------
+
+.. automodule:: pyneuroml.utils.simdata
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/refs.bib

@@ -20,4 +20,3 @@ @Article{Vella2014
   timestamp    = {2019-02-20},
   year         = {2014},
 }
-