Skip to content

Add lattice plugin architecture, stdface entry point, and documentation#53

Merged
k-yoshimi merged 21 commits intodevelopfrom
feature/solver-plugin-architecture
Jan 29, 2026
Merged

Add lattice plugin architecture, stdface entry point, and documentation#53
k-yoshimi merged 21 commits intodevelopfrom
feature/solver-plugin-architecture

Conversation

@k-yoshimi
Copy link
Copy Markdown
Contributor

  • Add LatticePlugin ABC and registry in lattice/init.py
  • Wrap all 10 lattice modules in plugin classes with auto-registration
  • Replace LATTICE_DISPATCH/BOOST_DISPATCH dicts with registry-based proxies
  • Update HPhi plugin to use lattice registry for boost dispatch
  • Add pyproject.toml with dev dependencies and entry points
  • Add stdface shell script entry point at project root
  • Add plugin tutorial (docs/tutorial_plugin.md) with solver and lattice examples
  • Update README.md and python/README.md with architecture, install, and usage docs
  • Rewrite test_lattice_dispatch.py to test plugin registry

- Add LatticePlugin ABC and registry in lattice/__init__.py
- Wrap all 10 lattice modules in plugin classes with auto-registration
- Replace LATTICE_DISPATCH/BOOST_DISPATCH dicts with registry-based proxies
- Update HPhi plugin to use lattice registry for boost dispatch
- Add pyproject.toml with dev dependencies and entry points
- Add stdface shell script entry point at project root
- Add plugin tutorial (docs/tutorial_plugin.md) with solver and lattice examples
- Update README.md and python/README.md with architecture, install, and usage docs
- Rewrite test_lattice_dispatch.py to test plugin registry

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The previous commit included only the files modified for the lattice
plugin architecture but omitted the rest of the stdface package
(core modules, solver plugins, writers) that had been created in
earlier refactoring steps but never committed. This caused
ModuleNotFoundError on CI.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Introduces a lattice plugin registry and plugin-wrapped lattice implementations, updates dispatch logic to use registry-backed proxies, adds an HPhi solver plugin hook for Boost, and adds packaging/docs/entry-point scaffolding plus updated tests.

Changes:

  • Added LatticePlugin ABC + registry (register_lattice, get_lattice, get_all_lattices) and converted lattice dispatch to registry-backed proxies.
  • Wrapped all lattice modules in plugin classes with auto-registration and updated HPhi post-lattice Boost handling to use the lattice registry.
  • Added packaging metadata (pyproject.toml), a root ./stdface launcher script, and updated README/tutorial + lattice dispatch tests.

Reviewed changes

Copilot reviewed 49 out of 49 changed files in this pull request and generated 25 comments.

Show a summary per file
File Description
test/unit/test_lattice_dispatch.py Rewrites dispatch tests to validate lattice registry + proxy behavior.
stdface Adds a root shell launcher that runs the Python entry point.
python/stdface/solvers/hphi/_plugin.py Adds HPhi solver plugin (post-lattice Boost, keyword/reset tables).
python/stdface/lattice/init.py Introduces LatticePlugin and lattice plugin registry + auto-discovery.
python/stdface/lattice/chain_lattice.py Converts chain lattice to plugin-registered module.
python/stdface/lattice/square_lattice.py Converts square/tetragonal lattice to plugin-registered module.
python/stdface/lattice/triangular_lattice.py Converts triangular lattice to plugin-registered module.
python/stdface/lattice/honeycomb_lattice.py Converts honeycomb lattice to plugin-registered module (incl. boost).
python/stdface/lattice/kagome.py Converts kagome lattice to plugin-registered module (incl. boost).
python/stdface/lattice/ladder.py Converts ladder lattice to plugin-registered module (incl. boost).
python/stdface/lattice/orthorhombic.py Converts orthorhombic lattice to plugin-registered module.
python/stdface/lattice/fc_ortho.py Converts face-centered orthorhombic lattice to plugin-registered module.
python/stdface/lattice/pyrochlore.py Converts pyrochlore lattice to plugin-registered module.
python/stdface/lattice/wannier90.py Adds Wannier90 lattice module + plugin registration.
python/stdface/core/stdface_main.py Replaces dispatch dicts with registry-backed proxies; refactors build/parse hooks.
python/pyproject.toml Adds packaging metadata, dev deps, console script + entry points.
python/history/refactoring_log.md Documents the refactoring steps for plugin architecture.
python/README.md Updates Python install/usage/docs to reflect plugin architecture and CLI.
docs/tutorial_plugin.md Adds tutorial documentation for adding lattice/solver plugins.
README.md Updates top-level docs for install/usage and new architecture.
Comments suppressed due to low confidence (1)

python/pyproject.toml:40

  • [tool.setuptools.packages.find] uses include = ["stdface*"], but the top-level python/stdface/ directory has no __init__.py (namespace package), so setuptools.find_packages will typically not discover stdface.lattice / stdface.core packages. Either add python/stdface/__init__.py (making it a regular package) or enable namespace package discovery (e.g. namespaces = true) / use find_namespace_packages.
[tool.setuptools.packages.find]
include = ["stdface*"]


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +20 to +25
[project.entry-points."stdface.solvers"]
hphi = "stdface.solvers.hphi:HPhiPlugin"
mvmc = "stdface.solvers.mvmc:MVMCPlugin"
uhf = "stdface.solvers.uhf:UHFPlugin"
hwave = "stdface.solvers.hwave:HWavePlugin"

Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The declared solver entry points reference modules/classes that don’t exist in this PR state (e.g. stdface.solvers.mvmc, stdface.solvers.uhf, stdface.solvers.hwave, and even stdface.solvers.hphi:HPhiPlugin won’t resolve without an __init__.py exporting HPhiPlugin). Either add the missing solver packages (and export the classes) or remove/fix these entry point declarations.

Suggested change
[project.entry-points."stdface.solvers"]
hphi = "stdface.solvers.hphi:HPhiPlugin"
mvmc = "stdface.solvers.mvmc:MVMCPlugin"
uhf = "stdface.solvers.uhf:UHFPlugin"
hwave = "stdface.solvers.hwave:HWavePlugin"

Copilot uses AI. Check for mistakes.
Comment on lines +36 to +40
from .stdface_vals import (
StdIntList, ModelType, SolverType, MethodType,
NaN_i, NaN_d, NaN_c, UNSET_STRING,
)
from .param_check import exit_program
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These imports reference sibling modules that are not present under python/stdface/core/ (e.g. stdface_vals.py, param_check.py, keyword_parser.py). As-is, importing stdface.core.stdface_main will raise ModuleNotFoundError. Either move the existing implementations into python/stdface/core/ or change these imports to the actual module locations.

Copilot uses AI. Check for mistakes.
Comment on lines +27 to +36
from .input_params import input_spin_nn, input_spin, input_hopp, input_coulomb_v
from .interaction_builder import (
malloc_interactions,
add_neighbor_interaction, add_local_terms,
)
from .site_util import (
init_site, set_label, set_local_spin_flags,
lattice_gp,
)
from .boost_output import (
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This module imports .input_params, .interaction_builder, .site_util, and .boost_output, but those helper modules are not present under python/stdface/lattice/ (they currently exist under python/lattice/). Importing stdface.lattice.chain_lattice will fail with ModuleNotFoundError unless the helpers are moved or the imports are updated.

Suggested change
from .input_params import input_spin_nn, input_spin, input_hopp, input_coulomb_v
from .interaction_builder import (
malloc_interactions,
add_neighbor_interaction, add_local_terms,
)
from .site_util import (
init_site, set_label, set_local_spin_flags,
lattice_gp,
)
from .boost_output import (
from lattice.input_params import input_spin_nn, input_spin, input_hopp, input_coulomb_v
from lattice.interaction_builder import (
malloc_interactions,
add_neighbor_interaction, add_local_terms,
)
from lattice.site_util import (
init_site, set_label, set_local_spin_flags,
lattice_gp,
)
from lattice.boost_output import (

Copilot uses AI. Check for mistakes.
Comment on lines +8 to +15
from ...plugin import SolverPlugin, register
from ...core.stdface_vals import StdIntList, SolverType, MethodType, NaN_i, NaN_d
from ...core.keyword_parser import (
store_with_check_dup_s, store_with_check_dup_sl,
store_with_check_dup_i, store_with_check_dup_d,
)
from .writer import large_value, print_calc_mod, print_excitation, print_pump

Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This plugin module depends on several modules that are not present in the current package layout (stdface/plugin.py, stdface/core/stdface_vals.py, stdface/core/keyword_parser.py, stdface/solvers/hphi/writer.py, and stdface/writer/common_writer.py). As-is, importing stdface.solvers.hphi._plugin will raise ModuleNotFoundError, so the solver plugin registry/entry points won’t work until those modules are added/moved or the imports are updated to the actual locations.

Copilot uses AI. Check for mistakes.
Comment on lines +7 to +8
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PYTHONPATH="${SCRIPT_DIR}/python" exec python3 -m stdface "$@"
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This wrapper executes python3 -m stdface, but the repo currently does not contain a python/stdface/__main__.py module, so ./stdface ... will fail with No module named stdface.__main__ / No module named stdface. Either add a proper stdface/__main__.py (and package init if needed) or update the wrapper to invoke the existing CLI module directly (e.g., python/__main__.py).

Copilot uses AI. Check for mistakes.
add_neighbor_interaction, add_local_terms,
)
from .site_util import (
init_site, set_label, set_local_spin_flags,
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Import of 'set_label' is not used.

Suggested change
init_site, set_label, set_local_spin_flags,
init_site, set_local_spin_flags,

Copilot uses AI. Check for mistakes.
Comment on lines +19 to +20
import numpy as np

Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Import of 'np' is not used.

Suggested change
import numpy as np

Copilot uses AI. Check for mistakes.
add_neighbor_interaction, add_local_terms,
)
from .site_util import (
init_site, set_label, set_local_spin_flags,
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Import of 'set_label' is not used.

Suggested change
init_site, set_label, set_local_spin_flags,
init_site, set_local_spin_flags,

Copilot uses AI. Check for mistakes.
for a in plugin.aliases:
if a in self._BOOST_LATTICES:
result.append((a, plugin.boost))
except KeyError:
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'except' clause does nothing but pass and there is no explanatory comment.

Suggested change
except KeyError:
except KeyError:
# Alias is listed in _BOOST_LATTICES but no corresponding lattice plugin
# is registered; silently skip it when building the dispatch table.

Copilot uses AI. Check for mistakes.
try:
plugin = get_plugin(solver)
plugin.post_lattice(StdI)
except KeyError:
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'except' clause does nothing but pass and there is no explanatory comment.

Suggested change
except KeyError:
except KeyError:
# No plugin registered for this solver: post-lattice processing is optional.

Copilot uses AI. Check for mistakes.
k-yoshimi and others added 5 commits January 29, 2026 20:34
- site_util: hash-based cell index lookup (O(NCell) -> O(1) per call)
- interaction_builder: precompute spin ladder factors in general_j()
- common_writer: buffer greenone/greentwo file I/O with join()
- mvmc/writer: numpy-ize _compute_parallel_orbitals (O(N⁴) -> O(N²))
- mvmc/variational: vectorize Jastrow symmetrise with np.where

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
These modules were moved into the python/stdface/ package hierarchy
during the plugin architecture refactoring and are no longer needed
at their original locations.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Migrate __main__.py and all unit tests from old flat imports
(e.g. from stdface_vals import ...) to the new package structure
(e.g. from stdface.core.stdface_vals import ...). Also update
test_solver_writer.py for the plugin architecture rename.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- writer.py: buffer all file I/O (print_orb, orbitalidxpara,
  orbitalidxgen, gutzwilleridx) with join() instead of per-line write
- writer.py: replace O(NOrb × N²) symmetrise loop with single-pass
  reverse map construction + targeted updates
- variational.py: buffer jastrowidx.def and qptransidx.def I/O
- variational.py: single-pass reverse map for Jastrow symmetrise
- variational.py: pre-compute cell_vectors and sectors outside loops
  in generate_orb and _jastrow_global_optimization
- common_writer.py: pre-compute spin_max and is_local_spin lookup
  tables in GreenFunctionIndices.__init__ to eliminate per-call
  overhead in deeply nested Green function index generation loops

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Buffer file I/O for HPhi excitation/pump writers and all interaction writers
- Use list comprehensions and itertools.product for Green function index generation
- Eliminate inner loop in green2_corr by computing spin4 directly from constraint
- Vectorize Wannier90 inversion symmetry check with numpy broadcasting

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 75 out of 77 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (13)

python/stdface/core/stdface_main.py:97

  • BOOST_DISPATCH relies on a hard-coded _BOOST_LATTICES alias set. This duplicates information already present in lattice plugins and can silently get out of sync if aliases change or new boost-capable lattices are added. Consider deriving boost support from the plugin itself (e.g., include aliases where plugin.boost is overridden vs LatticePlugin.boost) to keep the proxy accurate without manual updates.
    python/stdface/core/stdface_main.py:427
  • SolverPlugin defines an init_fields() hook for adding dynamic attributes, but the runtime never calls it. As a result, plugins cannot safely declare reset_arrays for dynamically created arrays (getattr/arr[...] would fail). Consider calling plugin.init_fields(StdI) before applying plugin.reset_scalars/reset_arrays in _apply_field_resets (or early in _reset_vals).
    python/stdface/writer/common_writer.py:804
  • print_2_green builds an in-memory list of every output line and then joins it into a single string. For realistic/large systems, greentwo.def can be extremely large (O(nsite^4)), so this approach can spike memory usage and potentially crash the process. Prefer streaming writes (write header, then write each row incrementally) or use fp.writelines over an iterator without materializing the full content in memory.
    python/stdface/writer/interaction_writer.py:147
  • _write_interaction_file accumulates the entire file contents into a Python list before writing. Interaction files (especially InterAll) can be very large, so buffering all lines in memory can cause high peak RAM usage. Consider writing the header immediately and then writing each term as it is generated (or using fp.writelines with a generator) to keep memory bounded.
    python/stdface/core/stdface_model_util.py:49
  • Import of 'exit_program' is not used.
    Import of 'print_val_d' is not used.
    Import of 'print_val_dd' is not used.
    Import of 'print_val_c' is not used.
    Import of 'print_val_i' is not used.
    Import of 'not_used_d' is not used.
    Import of 'not_used_j' is not used.
    Import of 'not_used_i' is not used.
    Import of 'required_val_i' is not used.
    python/stdface/core/stdface_model_util.py:55
  • Import of 'input_spin_nn' is not used.
    Import of 'input_spin' is not used.
    Import of 'input_coulomb_v' is not used.
    Import of 'input_hopp' is not used.
    python/stdface/core/stdface_model_util.py:59
  • Import of 'print_xsf' is not used.
    Import of 'print_geometry' is not used.
    python/stdface/core/stdface_model_util.py:69
  • Import of 'trans' is not used.
    Import of 'hopping' is not used.
    Import of 'hubbard_local' is not used.
    Import of 'mag_field' is not used.
    Import of 'intr' is not used.
    Import of 'general_j' is not used.
    Import of 'coulomb' is not used.
    Import of 'malloc_interactions' is not used.
    python/stdface/core/stdface_model_util.py:75
  • Import of 'set_label' is not used.
    Import of '_fold_site' is not used.
    Import of 'init_site' is not used.
    Import of 'find_site' is not used.
    test/unit/test_hphi_writer.py:47
  • Import of 'print_excitation' is not used.
    Import of 'print_pump' is not used.
    test/unit/test_interaction_writer.py:24
  • Import of '_process_interaction' is not used.
    python/stdface/core/stdface_main.py:123
  • 'except' clause does nothing but pass and there is no explanatory comment.
    python/stdface/core/stdface_main.py:560
  • 'except' clause does nothing but pass and there is no explanatory comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +154 to +158
def _discover_lattices() -> None:
"""Import all lattice modules to trigger auto-registration."""
from . import chain_lattice, square_lattice, ladder, triangular_lattice # noqa: F401
from . import honeycomb_lattice, kagome, orthorhombic, fc_ortho, pyrochlore # noqa: F401
from . import wannier90 # noqa: F401
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

_discover_lattices() hard-codes imports of built-in lattice modules and does not load entry points (even though pyproject.toml defines "stdface.lattices" entry points). If the intent is to support external lattice plugins, add entry-point discovery (importlib.metadata) here; otherwise the entry-point configuration is unused and the architecture still requires editing this function for new lattices.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot open a new pull request to apply changes based on this feedback

Comment on lines +256 to +265
def _discover_plugins() -> None:
"""Load built-in plugins by importing the solvers package.

This function is called lazily on first access to ensure plugins
are registered even if the solvers package hasn't been imported yet.
"""
try:
import stdface.solvers # noqa: F401 — triggers auto-registration
except ImportError:
pass
Copy link

Copilot AI Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

_discover_plugins() only imports stdface.solvers, but pyproject.toml declares entry points under "stdface.solvers" for plugin extensibility. Without loading entry points via importlib.metadata, externally installed solver plugins will never be discovered, and the entry-point configuration is effectively unused.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot open a new pull request to apply changes based on this feedback

Copy link
Copy Markdown

Copilot AI commented Jan 29, 2026

@k-yoshimi I've opened a new pull request, #54, to work on those changes. Once the pull request is ready, I'll request review from you.

k-yoshimi and others added 2 commits January 29, 2026 21:08
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Copy link
Copy Markdown

Copilot AI commented Jan 29, 2026

@k-yoshimi I've opened a new pull request, #55, to work on those changes. Once the pull request is ready, I'll request review from you.

Copy link
Copy Markdown

Copilot AI commented Jan 29, 2026

@k-yoshimi I've opened a new pull request, #56, to work on those changes. Once the pull request is ready, I'll request review from you.

Copy link
Copy Markdown

Copilot AI commented Jan 29, 2026

@k-yoshimi I've opened a new pull request, #57, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot AI and others added 4 commits January 29, 2026 12:11
Co-authored-by: k-yoshimi <4516893+k-yoshimi@users.noreply.github.com>
Co-authored-by: k-yoshimi <4516893+k-yoshimi@users.noreply.github.com>
Co-authored-by: k-yoshimi <4516893+k-yoshimi@users.noreply.github.com>
[WIP] Update lattice plugin architecture and documentation
Copilot AI and others added 5 commits January 29, 2026 12:12
Co-authored-by: k-yoshimi <4516893+k-yoshimi@users.noreply.github.com>
[WIP] WIP address feedback on lattice plugin architecture
Remove unused NaN_d import from test_stdface_main_helpers.py
…-one

Add explanatory comment for ImportError handling in plugin discovery
@k-yoshimi k-yoshimi merged commit 9357bbf into develop Jan 29, 2026
12 checks passed
@k-yoshimi k-yoshimi deleted the feature/solver-plugin-architecture branch January 29, 2026 12:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants