abacuslite 1.1.0__tar.gz

abacuslite-1.1.0/AGENTS.md

@@ -0,0 +1,50 @@
+# abacuslite development
+
+## Goal and scope
+
+Maintain one independently installable ABACUS calculator and I/O plugin for ASE.
+Preserve public `abacuslite` imports, upstream attribution and read-only parsing
+while consolidating general-purpose fixes from ABACUS and ATST. Pure file I/O
+must work without an ABACUS executable.
+
+## Upstream and downstream boundaries
+
+- ASE supplies calculator contracts and optimization/MD/NEB algorithms.
+- ABACUS owns the engine, output formats, assets and engine integration tests.
+  Support develop's newer format and LTS through `legacyio`; bind reader
+  selection to each calculator instance, even when LTS has no bundled interface.
+- ATST consumes calculator/I/O behavior and owns workflow and launcher policy.
+- Forge consumes the optional parser and owns its native default and result
+  contracts. ATST and Forge are not runtime dependencies of this package.
+- Keep general parser/calculator fixes here. Compatibility adapters may forward
+  to this implementation; do not add duplicate parsers, schedulers, workflow
+  orchestration or consumer result schemas to the package.
+
+## Development workflow
+
+1. Read [the documentation index](docs/README.md), [design](docs/design.md),
+   [module reference](docs/reference.md) and [source provenance](UPSTREAM.md)
+   for the affected area. Reuse an applicable plan for coordinated work.
+2. Make focused, reversible changes within the agreed design. Update the
+   relevant design/plan before changing public or cross-repository boundaries;
+   continue within approved scope without reopening routine implementation choices.
+3. Add regressions for observable behavior changes. For behavior-preserving
+   extraction or packaging changes, compare baseline and candidate behavior.
+   Preserve units, atom order and missing-value meaning. Parsing existing
+   output must not modify or delete input/output files.
+4. Follow [CONTRIBUTING.md](CONTRIBUTING.md) for commands. Default tests are
+   offline; real-engine and installed-consumer checks require explicit opt-in
+   and supplied dependencies/assets. Validate built wheels outside the source
+   checkout; source-only success is not release evidence.
+5. Test affected develop/LTS and consumer boundaries using the
+   [compatibility guide](docs/compatibility-ci.md). Fixture success does not
+   establish engine compatibility; report local results, remote CI and merge
+   enforcement separately. Validate locally before PR delivery.
+6. Use English for documentation and new diagnostics/docstrings, retain source
+   attribution, and record material compatibility changes in `CHANGELOG.md`.
+   Obtain independent review before integration. PyPI publication requires
+   validated artifacts and explicit release authorization.
+
+Current guidance lives in the root entry documents and `docs/`. Implementation
+plans and dated evidence live in `docs/superpowers/plans/`; historical results
+apply only to their recorded revisions and environments.

abacuslite-1.1.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 1.1.0
+
+- Provide the independent ASE plugin as a wheel and source distribution with
+  unchanged public imports. Preserve the validated runtime from the final
+  candidate; the stable release adds packaging, documentation and release gates.
+
+- Honor explicit engine/consumer pytest markers and reject unknown markers or
+  configuration keys; offline tests no longer depend on checkout directory or
+  function names. Validate wheel and sdist tests outside the checkout, and
+  include the source-only test launchers in the sdist.
+- Restore the skipped pseudopotential/orbital filename-selection tests with
+  self-contained temporary assets, without requiring an ABACUS installation.
+- Give cell relaxation, DOS and metadynamics examples separate calculation
+  directories, and use the standard `abacus` command in the NEB default launcher.
+  Check default and overridden example settings before engine execution.
+- Preserve explicit ASE atomic velocities in STRU, converting from Angstrom
+  per ASE time unit to Bohr per atomic time unit and maintaining species order;
+  atoms without velocities retain the existing zero initialization.
+- Prefer `MD_dump` for LTS native MD geometry; retain complete single-file
+  `running_md.log` trajectories when no dump exists. Assemble physical
+  Angstrom coordinates/cells and periodic ASE frames, recognize unpadded LTS
+  ionic-step headers, and reject incomplete geometry or malformed dumps
+  without changing SCF/relax output semantics.
+- Align the default SCF structure-identity tolerance with ATST 2.2.9:
+  `1e-5` Angstrom for cell components and periodic Cartesian residuals,
+  with `rtol=0`. Explicit `atol` overrides remain supported. The former
+  `1e-5` to `1e-4` interval is now rejected rather than silently selecting
+  a mismatching SCF frame; native relax/MD last-frame selection is unchanged.
+- Establish an independent source package from ABACUS develop `4b92455ca`,
+  retaining original attribution, module paths and socket support.
+- Integrate ATST SCF structure-frame matching, periodic equivalence and atom
+  mapping validation, actual STRU filename handling, and Fermi-level retention.
+- Correct decimal point-KPT parsing and tolerate absent Fermi levels.
+- Normalize Cartesian log coordinates by the lattice constant when matching
+  SCF frames to STRU, for both output readers.
+- Convert latest-format native MD `MD_dump` lattice vectors from alat units to
+  Angstrom and mark those ASE frames periodic; dump-reader dictionaries and
+  their already-Angstrom Cartesian positions retain their existing units.
+- Keep the upstream read-only `eig_occ.txt` behavior: repeated collection no
+  longer consumes the input file. This intentionally differs from old ATST.
+- Isolate each calculator's output-format selection; compatibility switch
+  calls affect new bare templates only, not existing calculator instances.
+- Add persistent installed ATST/Forge consumer CI, bidirectional reader
+  isolation regressions and a cross-repository compatibility guide.
+- Make all examples accept explicit engine/asset environment settings and
+  document source layout, installation and consumer migration.
+- Separate offline tests from opt-in engine tests and package source fixtures.
+- Raise the ASE dependency floor to 3.28 for the supported candidate matrix;
+  this release does not claim the old unverified `ase>=3.22` range.
+
+Publication status and artifact identities are recorded in the
+[release record](docs/superpowers/plans/2026-10-17-1.1.0-release.md).
+Existing consumers must validate their installed integration
+before removing vendored implementations or changing production dependencies.

abacuslite-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# Contributing
+
+General ASE calculator and ABACUS I/O fixes belong in this package. ABACUS
+owns the engine and its integration harness; ATST owns workflow and launcher
+policy. See the [integration audit](docs/upstream-integration.md) and
+[cross-repository CI guide](docs/compatibility-ci.md) before changing a boundary.
+
+## Development setup
+
+From the repository root in a suitable Python environment:
+
+```bash
+python -m pip install -e '.[dev]'
+python -m pytest -q
+```
+
+The default suite is offline; engine and external-consumer tests are opt-in.
+`tests/integration/` is marked `engine`, and `tests/consumers/` is marked
+`consumer`. Tests elsewhere must use `@pytest.mark.engine` or
+`@pytest.mark.consumer` when they need those resources; function names and
+checkout directory names do not select a test tier. Unknown markers and
+pytest configuration keys fail validation. `-m engine` selects tests but does
+not enable execution without `--run-engine`.
+
+Editable installs are appropriate for development. For acceptance, build wheel
+and sdist distributions and check their metadata:
+
+```bash
+python -m build
+python -m twine check --strict dist/*
+```
+
+Install the built wheel and pytest in a fresh environment, run `pip check`,
+and copy `tests/`, `examples/` and `pyproject.toml` to a directory outside the
+source checkout. Run `python -m pytest -q` there without a source `PYTHONPATH`.
+Verify that `abacuslite.__file__` resolves inside that environment; the
+[migration guide](docs/migration.md#install-one-implementation) provides the
+check. Include `examples/` because offline tests verify their startup. Repeat
+with a wheel rebuilt from the sdist when validating distribution changes.
+Use the tests, examples and configuration extracted from that sdist for the
+second run, so missing distribution files cannot be masked by the checkout.
+CI uses this layout for Python 3.10 with the declared direct dependency floors
+and Python 3.12 with current dependencies. Tests and examples ship in the
+sdist; the wheel contains the runtime package only.
+Use `python -I -m pytest -q` for artifact validation: example subprocesses
+preserve isolated mode and check that a conflicting `PYTHONPATH` is ignored.
+
+## Engine and consumer checks
+
+For the package's opt-in engine tests, supply the matching ABACUS build and
+the tests' named pseudopotential/orbital assets:
+
+```bash
+export ABACUS_COMMAND='mpirun -np 2 abacus'
+export ABACUS_PP_ORB=/absolute/path/to/ABACUS/tests/PP_ORB
+export OMP_NUM_THREADS=1
+python -m pytest --run-engine -m engine -q
+```
+
+These imported tests contain engine-specific references and do not replace the
+stronger two-format engine harness. Consult the [compatibility guide](docs/compatibility-ci.md)
+for installed ATST/Forge checks, current develop/LTS evidence and pending CI
+work. Fixture or example-startup success alone is not real-engine acceptance.
+
+## Changes and review
+
+Add a regression for the observable bug, with a small attributed fixture when
+output formats matter. Preserve units,
+atom ordering, missing-value meaning, readonly parsing and public imports.
+Validate the built wheel, not only editable source. For a parser or calculator
+change, identify affected supported engine versions and consumers and collect
+real-engine evidence where needed before release.
+
+CI and fixtures are part of the contract: explain changed expectations and
+link paired repository PRs. Internal refactoring is welcome when the behavior
+continues to pass. Breaking public behavior needs an explicit migration and
+versioning decision; do not silently weaken existing assertions.
+
+Historical implementation evidence is retained in the
+[bootstrap record](docs/superpowers/plans/2026-10-16-standalone-bootstrap.md)
+and [installed-consumer CI record](docs/superpowers/plans/2026-10-16-cross-repository-regressions.md).
+Current engine/consumer results and subsequent plans are linked from the
+compatibility guide.
+
+## Releasing
+
+Stable releases require explicit maintainer authorization, reviewed changes,
+installed-wheel/sdist checks and successful `Package tests` for the release
+tag. Preserve affected develop/LTS and consumer evidence. Set the version in
+`pyproject.toml`, update the changelog, and merge the reviewed source into main
+before creating its `vMAJOR.MINOR.PATCH` tag. Never move a published tag or
+replace a published distribution.
+
+The manual `Publish to PyPI` workflow must run from main. Supply the stable tag
+and the successful **tag push** run ID of `Package tests`. It checks the source
+repository, workflow, event, revision, main ancestry and artifact versions,
+then publishes that run's `distributions-3.12` artifact without rebuilding.
+Only the upload job receives OIDC permission. The `pypi` GitHub environment
+must match a PyPI Trusted Publisher for owner `QuantumMisaka`, repository
+`abacuslite`, workflow `publish.yml`, environment `pypi`. A first release uses
+a pending publisher configured by the maintainer in their PyPI account.
+
+After upload, compare PyPI's SHA256 digests with the workflow summary and
+verify `pip install abacuslite==VERSION` and `pip check` in a fresh environment.
+If an upload partially succeeds, inspect the registry before retrying; do not
+silently skip conflicting artifacts. Keep the release's source/run IDs and
+verification evidence in its record under `docs/superpowers/plans/`.

abacuslite-1.1.0/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+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.

abacuslite-1.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include CONTRIBUTING.md
+include LICENSE UPSTREAM.md CHANGELOG.md AGENTS.md
+include src/abacuslite/xtest.sh
+recursive-include tests *.py *.sh
+recursive-include tests/fixtures *
+recursive-include examples *.py
+recursive-include docs *.md
+global-exclude __pycache__ *.py[cod]

abacuslite-1.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: abacuslite
+Version: 1.1.0
+Summary: A lightweight ABACUS calculator and I/O plugin for ASE
+Author: Yuyang Ji, Zhenxiong Shen, Yike Huang, Zhaoqing Liu
+License-Expression: LGPL-3.0-only
+Project-URL: Homepage, https://github.com/QuantumMisaka/abacuslite
+Project-URL: Documentation, https://github.com/QuantumMisaka/abacuslite/tree/main/docs
+Project-URL: Issues, https://github.com/QuantumMisaka/abacuslite/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ase<4,>=3.28
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: seekpath<3,>=2.2
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# abacuslite
+
+A lightweight [ABACUS](https://github.com/deepmodeling/abacus-develop) calculator
+and I/O plugin for [ASE](https://ase-lib.org/), combining the ABACUS interface
+with general-purpose fixes from [ATST](https://github.com/QuantumMisaka/atst-tools).
+It preserves the existing `abacuslite` imports and works without patching ASE.
+
+Use it for energy, forces and stress in ASE calculations, or to read and write
+ABACUS files without launching an engine. Both develop's newer output format
+and LTS v3.10.x are supported; the fixed-cell socket calculator requires an
+engine with socket support.
+
+**Release line:** `1.1.0`. Local develop/LTS interface checks have passed;
+dual-engine PR CI is still planned. See the [compatibility record](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/compatibility-ci.md)
+for tested snapshots and the [release record](https://github.com/QuantumMisaka/abacuslite/blob/main/docs/superpowers/plans/2026-10-17-1.1.0-release.md)
+for publication status.
+
+## Installation
+
+Requires **Python 3.10+** and **ASE 3.28+ (<4)**. From a POSIX shell:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install 'abacuslite==1.1.0'
+python -m pip check
+```
+
+Pip installs ASE, NumPy and seekpath. ABACUS and its pseudopotential/orbital
+assets are supplied separately. Existing environments and callers should
+follow the [migration guide](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/migration.md).
+
+## Quick start
+
+Read an existing ABACUS input file without an engine:
+
+```python
+from abacuslite.io.generalio import read_input
+
+parameters = read_input("INPUT")
+print(parameters)
+```
+
+Examples are distributed in the source release. For a real calculation,
+get the matching checkout, configure the engine and assets, and run an example:
+
+```bash
+git clone --branch v1.1.0 https://github.com/QuantumMisaka/abacuslite.git
+cd abacuslite
+export ABACUS_COMMAND='mpirun -np 2 abacus'
+export ABACUS_PP_ORB=/absolute/path/to/ABACUS/tests/PP_ORB
+export OMP_NUM_THREADS=1
+python examples/scf.py
+```
+
+This example uses `genelpa`; select a solver supported by your ABACUS build.
+The [usage guide](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/usage.md) lists required assets, example cleanup behavior,
+calculator configuration and the complete example collection.
+
+## Documentation
+
+See the [documentation index](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/README.md) for current guides and development records.
+
+| Task | Guide |
+| --- | --- |
+| Configure calculators, read output, run examples | [Usage](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/usage.md) |
+| Migrate ABACUS/ATST callers | [Migration](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/migration.md) |
+| Set up development, run tests and validate packages | [Contributing](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/CONTRIBUTING.md) |
+| Understand modules and package boundaries | [Module reference](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/reference.md) |
+| Check supported engines, CI and acceptance evidence | [Compatibility](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/compatibility-ci.md) |
+| Review changes and source attribution | [Changelog](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/CHANGELOG.md), [provenance](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/UPSTREAM.md) |
+
+## Authors and maintenance
+
+- [Yuyang Ji (@jiyuyang)](https://github.com/jiyuyang)
+- [Zhenxiong Shen (@Shen-Zhen-Xiong)](https://github.com/Shen-Zhen-Xiong)
+- [Yike Huang (@kirk0830)](https://github.com/kirk0830)
+- [Zhaoqing Liu (@QuantumMisaka)](https://github.com/QuantumMisaka)
+
+The independent package is maintained by QuantumMisaka. Thanks to the ABACUS
+and ATST contributors; original attribution is preserved in [UPSTREAM.md](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/UPSTREAM.md).
+
+Licensed under [LGPL-3.0-only](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/LICENSE). Report plugin issues at
+[QuantumMisaka/abacuslite](https://github.com/QuantumMisaka/abacuslite/issues).

abacuslite-1.1.0/README.md

@@ -0,0 +1,84 @@
+# abacuslite
+
+A lightweight [ABACUS](https://github.com/deepmodeling/abacus-develop) calculator
+and I/O plugin for [ASE](https://ase-lib.org/), combining the ABACUS interface
+with general-purpose fixes from [ATST](https://github.com/QuantumMisaka/atst-tools).
+It preserves the existing `abacuslite` imports and works without patching ASE.
+
+Use it for energy, forces and stress in ASE calculations, or to read and write
+ABACUS files without launching an engine. Both develop's newer output format
+and LTS v3.10.x are supported; the fixed-cell socket calculator requires an
+engine with socket support.
+
+**Release line:** `1.1.0`. Local develop/LTS interface checks have passed;
+dual-engine PR CI is still planned. See the [compatibility record](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/compatibility-ci.md)
+for tested snapshots and the [release record](https://github.com/QuantumMisaka/abacuslite/blob/main/docs/superpowers/plans/2026-10-17-1.1.0-release.md)
+for publication status.
+
+## Installation
+
+Requires **Python 3.10+** and **ASE 3.28+ (<4)**. From a POSIX shell:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install 'abacuslite==1.1.0'
+python -m pip check
+```
+
+Pip installs ASE, NumPy and seekpath. ABACUS and its pseudopotential/orbital
+assets are supplied separately. Existing environments and callers should
+follow the [migration guide](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/migration.md).
+
+## Quick start
+
+Read an existing ABACUS input file without an engine:
+
+```python
+from abacuslite.io.generalio import read_input
+
+parameters = read_input("INPUT")
+print(parameters)
+```
+
+Examples are distributed in the source release. For a real calculation,
+get the matching checkout, configure the engine and assets, and run an example:
+
+```bash
+git clone --branch v1.1.0 https://github.com/QuantumMisaka/abacuslite.git
+cd abacuslite
+export ABACUS_COMMAND='mpirun -np 2 abacus'
+export ABACUS_PP_ORB=/absolute/path/to/ABACUS/tests/PP_ORB
+export OMP_NUM_THREADS=1
+python examples/scf.py
+```
+
+This example uses `genelpa`; select a solver supported by your ABACUS build.
+The [usage guide](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/usage.md) lists required assets, example cleanup behavior,
+calculator configuration and the complete example collection.
+
+## Documentation
+
+See the [documentation index](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/README.md) for current guides and development records.
+
+| Task | Guide |
+| --- | --- |
+| Configure calculators, read output, run examples | [Usage](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/usage.md) |
+| Migrate ABACUS/ATST callers | [Migration](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/migration.md) |
+| Set up development, run tests and validate packages | [Contributing](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/CONTRIBUTING.md) |
+| Understand modules and package boundaries | [Module reference](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/reference.md) |
+| Check supported engines, CI and acceptance evidence | [Compatibility](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/docs/compatibility-ci.md) |
+| Review changes and source attribution | [Changelog](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/CHANGELOG.md), [provenance](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/UPSTREAM.md) |
+
+## Authors and maintenance
+
+- [Yuyang Ji (@jiyuyang)](https://github.com/jiyuyang)
+- [Zhenxiong Shen (@Shen-Zhen-Xiong)](https://github.com/Shen-Zhen-Xiong)
+- [Yike Huang (@kirk0830)](https://github.com/kirk0830)
+- [Zhaoqing Liu (@QuantumMisaka)](https://github.com/QuantumMisaka)
+
+The independent package is maintained by QuantumMisaka. Thanks to the ABACUS
+and ATST contributors; original attribution is preserved in [UPSTREAM.md](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/UPSTREAM.md).
+
+Licensed under [LGPL-3.0-only](https://github.com/QuantumMisaka/abacuslite/blob/v1.1.0/LICENSE). Report plugin issues at
+[QuantumMisaka/abacuslite](https://github.com/QuantumMisaka/abacuslite/issues).

abacuslite-1.1.0/UPSTREAM.md

@@ -0,0 +1,64 @@
+# Source provenance
+
+Initial snapshot imported from `deepmodeling/abacus-develop`,
+`interfaces/ASE_interface`, commit
+`4b92455cab1b1a51e8534b7eb869798ae1241b1b` (2026-10-16).
+
+Original repository: https://github.com/deepmodeling/abacus-develop
+Original history: https://github.com/deepmodeling/abacus-develop/commits/4b92455cab1b1a51e8534b7eb869798ae1241b1b/interfaces/ASE_interface
+
+This is a snapshot import; the original Git history is linked, not rewritten
+or claimed as newly authored. Original author notices are retained. The root
+LICENSE is copied from the same ABACUS commit. ATST adaptations are recorded below with their source and regression evidence.
+
+## Integrated ATST adaptations
+
+Source: https://github.com/QuantumMisaka/atst-tools/tree/45d8c78de8a605c127cd4c36742d0c9525a0a6b6
+
+The SCF frame helpers, template input/result handling, point-KPT reader,
+missing-Fermi tolerance, frame-selection regressions and multiframe fixtures
+are adapted from `src/atst_tools/external/ASE_interface` and `tests/unit`
+at that revision. ATST authorship and its LGPL-3.0-or-later licensing are
+acknowledged; the combined distribution retains the ABACUS LGPL-3.0 terms.
+The older ATST implementation does not replace the newer ABACUS socket or
+execution diagnostics. The upstream non-destructive `eig_occ.txt` reader is
+retained, and its repeatability is tested.
+
+The independent package additionally isolates calculator reader selection
+from the compatibility global default. Behavioral changes and validation
+are recorded in CHANGELOG.md and the implementation plan.
+
+## Independent maintenance after the source import
+
+The LTS native-MD compatibility correction in `generalio.py` and `legacyio.py`
+is maintained by the independent package after the ABACUS snapshot. STRU
+velocity conversion follows the ABACUS develop
+`source/source_md/md_func.cpp` and LTS `source/module_md/md_func.cpp` contract:
+the MD dump writes internal atomic-unit velocity divided by
+`ANGSTROM_AU * AU_to_FS` as Angstrom/fs. The real, unchanged v3.10.1 output
+in `tests/fixtures/lts_native_md` and focused unit regressions establish
+three-frame MD dump assembly, original-byte preservation and explicit failure
+for incomplete log-only trajectories or incomplete dumps. Earlier complete
+single-file `running_md.log` trajectories remain supported when `MD_dump` is
+absent. Existing SCF/relax geometry assembly remains on the legacy running-log
+path.
+
+The default SCF identity tolerance is aligned with ATST 2.2.9 at
+`1081b9d1fed06842ee1d95dfbeb542ed81c57d49`: `1e-5` Angstrom, no relative
+tolerance, with explicit caller overrides retained. Boundary regressions
+exercise cell and position differences of `9e-6`, `11e-6` and `5e-5` Angstrom.
+Other implementation differences are not overwritten by this synchronization.
+
+The latest-format native MD cell conversion in `src/abacuslite/io/latestio.py`
+is an independent abacuslite correction made after the attributed ABACUS
+snapshot and ATST adaptations. The real two-frame
+`tests/fixtures/multiframe_md_latest` regression checks the dump-reader
+dictionary contract and the assembled ASE cell, positions, volume and energies.
+Only the latest-format native MD frames are additionally marked periodic.
+The legacy running-log reader already converts its cell to Angstrom and is
+unchanged by this correction.
+
+Additional generic fixed-density, native version-probe and backup-suffix
+regressions are adapted from ATST `tests/unit/test_abacuslite_profile.py` at
+the same revision. The [integration audit](docs/upstream-integration.md) maps
+all substantive source differences to retained behavior and test ownership.