graspkit-atomic 3.4.1__tar.gz → 3.4.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. graspkit_atomic-3.4.3/INSTALL.md +63 -0
  2. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/PKG-INFO +27 -41
  3. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/README.md +26 -40
  4. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/README_zh.md +22 -36
  5. graspkit_atomic-3.4.3/docs/releasing.md +201 -0
  6. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/version.py +1 -1
  7. graspkit_atomic-3.4.1/INSTALL.md +0 -79
  8. graspkit_atomic-3.4.1/docs/releasing.md +0 -156
  9. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/.gitignore +0 -0
  10. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/LICENSE +0 -0
  11. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/build_package.py +0 -0
  12. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/pyproject.toml +0 -0
  13. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/scripts/check_release.py +0 -0
  14. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/CSFs_processor/__init__.py +0 -0
  15. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/CSFs_processor/coupling.py +0 -0
  16. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/CSFs_processor/extraction.py +0 -0
  17. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/CSFs_processor/selection.py +0 -0
  18. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/CSFs_processor/validation.py +0 -0
  19. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/__init__.py +0 -0
  20. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/__init__.py +0 -0
  21. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/file_locator.py +0 -0
  22. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/__init__.py +0 -0
  23. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/base_loader.py +0 -0
  24. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/binary_file_loader.py +0 -0
  25. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/energy_file_loader.py +0 -0
  26. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/gj_factor_loader.py +0 -0
  27. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/hyperfine_structure_loader.py +0 -0
  28. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/lsj_comp_loader.py +0 -0
  29. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/mix_coef_loader.py +0 -0
  30. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/radial_analysis_loader.py +0 -0
  31. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/radial_wavefunction_loader.py +0 -0
  32. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/loaders/transition_loader.py +0 -0
  33. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/mix_coef_writer.py +0 -0
  34. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/data_IO/produced_data_writor.py +0 -0
  35. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/grasp_data_extractor/__init__.py +0 -0
  36. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/grasp_data_extractor/asfs_data_processor.py +0 -0
  37. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/grasp_data_extractor/radial_analysis.py +0 -0
  38. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/grasp_data_extractor/radial_wavefunction_processor.py +0 -0
  39. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/grasp_data_extractor/rmix_data_processor.py +0 -0
  40. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/grasp_data_extractor/transition_data_processor.py +0 -0
  41. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/py.typed +0 -0
  42. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/utils/__init__.py +0 -0
  43. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/utils/data_modules.py +0 -0
  44. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/utils/environment_config.py +0 -0
  45. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/utils/quadrupole_deformation.py +0 -0
  46. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit/utils/tool_function.py +0 -0
  47. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit_plot/__init__.py +0 -0
  48. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit_plot/fig_settings.py +0 -0
  49. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit_plot/mid_coupling.py +0 -0
  50. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit_plot/plot_functions.py +0 -0
  51. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.3}/src/graspkit_plot/radial_analysis.py +0 -0
@@ -0,0 +1,63 @@
1
+ # Installation
2
+
3
+ `graspkit-atomic` requires Python 3.14 or newer. It provides the `graspkit` and
4
+ `graspkit_plot` import packages. The distribution name is `graspkit-atomic`, previously `grasp-atomic-kit`;
5
+ existing import statements need no changes. When migrating an existing project,
6
+ replace the old dependency rather than declaring both distributions, which
7
+ provide the same Python packages.
8
+
9
+ ## Install from PyPI
10
+
11
+ ```bash
12
+ python -m pip install graspkit-atomic
13
+ ```
14
+
15
+ For a fixed release:
16
+
17
+ ```bash
18
+ python -m pip install "graspkit-atomic==3.4.3"
19
+ ```
20
+
21
+ ## Declare a project dependency
22
+
23
+ Add `"graspkit-atomic==3.4.3"` to the existing `[project].dependencies` list in
24
+ your own `pyproject.toml`. A minimal example:
25
+
26
+ ```toml
27
+ [project]
28
+ name = "atomic-analysis"
29
+ version = "0.1.0"
30
+ requires-python = ">=3.14"
31
+ dependencies = ["graspkit-atomic==3.4.3"]
32
+ ```
33
+
34
+ For a uv-managed project, run `uv sync` after editing `pyproject.toml`, then
35
+ `uv run python analysis.py` to run your own script in its environment. To let uv
36
+ add the dependency and update the lockfile/environment in one step, use
37
+ `uv add graspkit-atomic`. See the [README](README.md#with-uv) for a new-project
38
+ example. Alternatively, install a pip-managed project with `python -m pip install .`.
39
+ Add `"rcsfs==1.3.1"` separately if your application also needs the Rust CSF library.
40
+
41
+ Pip installs the declared runtime dependencies; Rust and the GRASP executables
42
+ are not needed to install this Python library. Reading calculation results
43
+ requires the corresponding GRASP data files.
44
+
45
+ ## Local wheel or source installation
46
+
47
+ To install a downloaded wheel, use its exact filename:
48
+
49
+ ```bash
50
+ python -m pip install /path/to/graspkit_atomic-3.4.3-py3-none-any.whl
51
+ ```
52
+
53
+ A standalone source checkout also supports `python -m pip install .`.
54
+
55
+ ## Verification
56
+
57
+ ```bash
58
+ python -c "from graspkit.data_IO import EnergyFileLoader; print(EnergyFileLoader)"
59
+ python -c "import graspkit_plot; print(graspkit_plot.__file__)"
60
+ ```
61
+
62
+ For builds and artifact tests, see [the release guide](docs/releasing.md).
63
+ PyTorch and scikit-learn are not dependencies of this library.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: graspkit-atomic
3
- Version: 3.4.1
3
+ Version: 3.4.3
4
4
  Summary: Stable data I/O, processing, and plotting for GRASP calculations
5
5
  Project-URL: Homepage, https://github.com/YenochQin/graspkit
6
6
  Project-URL: Source, https://github.com/YenochQin/graspkit
@@ -50,8 +50,7 @@ Description-Content-Type: text/markdown
50
50
  English | [简体中文](README_zh.md)
51
51
 
52
52
  `graspkit` is the stable foundation for reading, processing, and plotting
53
- GRASP atomic-structure calculation results. Machine-learning workflow code is
54
- owned by the sibling `graspkit-tools` repository.
53
+ GRASP atomic-structure calculation results.
55
54
 
56
55
  ## Package structure
57
56
 
@@ -64,35 +63,31 @@ owned by the sibling `graspkit-tools` repository.
64
63
  quantum-number helpers.
65
64
  - `graspkit_plot`: plotting and publication-style helpers.
66
65
 
67
- The package deliberately does not contain ML models, training configuration,
68
- or iterative pipeline state. Those live under
69
- `graspkit-tools/ml_CSFs_selection_scripts/ml_csf_choosing/`.
70
-
71
66
  ## Installation
72
67
 
73
68
  Install [graspkit-atomic from PyPI](https://pypi.org/project/graspkit-atomic/)
74
69
  with Python 3.14 or newer. The distribution name is `graspkit-atomic`;
75
70
  its Python import packages are `graspkit` and `graspkit_plot`.
76
71
 
77
- ### With pip
72
+ ### With uv
78
73
 
79
- > The new PyPI name is prepared for publication. The installation commands below
80
- > apply after the first `graspkit-atomic` release.
74
+ Use [uv](https://docs.astral.sh/uv/getting-started/installation/) to manage the
75
+ environment and dependencies of your own analysis project. For a new project:
81
76
 
82
77
  ```bash
83
- python -m pip install graspkit-atomic
78
+ uv init --python 3.14 atomic-analysis
79
+ cd atomic-analysis
80
+ uv add graspkit-atomic
81
+ uv run python -c "import graspkit; print(graspkit.__version__)"
84
82
  ```
85
83
 
86
- To reproduce the current release exactly:
84
+ For an existing uv project using Python 3.14 or newer, run `uv add graspkit-atomic`
85
+ in its directory. This records the dependency in `pyproject.toml`, updates
86
+ `uv.lock`, and installs it in the project's `.venv`. Use `uv run python analysis.py`
87
+ to run your own analysis script; manual environment activation is not required.
88
+ To pin a particular release, use `uv add "graspkit-atomic==3.4.3"`.
87
89
 
88
- ```bash
89
- python -m pip install "graspkit-atomic==3.4.1"
90
- ```
91
-
92
- ### In pyproject.toml
93
-
94
- Add the dependency to your own project's existing `[project].dependencies`.
95
- A minimal example is:
90
+ You can also add the dependency to an existing `pyproject.toml` manually:
96
91
 
97
92
  ```toml
98
93
  [project]
@@ -100,20 +95,25 @@ name = "atomic-analysis"
100
95
  version = "0.1.0"
101
96
  requires-python = ">=3.14"
102
97
  dependencies = [
103
- "graspkit-atomic==3.4.1",
98
+ "graspkit-atomic==3.4.3",
104
99
  ]
105
100
  ```
106
101
 
107
- From your consuming project's directory, install the project and its dependencies:
102
+ Then run `uv sync` in that project's directory to resolve dependencies and
103
+ synchronize its environment. Commit `pyproject.toml` and `uv.lock` alongside
104
+ your analysis code to record the dependency choices.
105
+
106
+ ### With pip
107
+
108
+ To install into an existing Python environment:
108
109
 
109
110
  ```bash
110
- python -m pip install .
111
+ python -m pip install graspkit-atomic
111
112
  ```
112
113
 
113
- Both installation methods provide the same Python API. If your project also uses
114
- rCSFs, add `"rcsfs==1.3.1"` to the same dependency list. GraspKit's package includes
115
- the plotting API; ML training and workflow orchestration belong to `graspkit-tools`.
116
- See [INSTALL.md](INSTALL.md) for local-wheel and contributor installation details.
114
+ Both methods provide the same Python API, including plotting. If your project
115
+ also uses rCSFs, add it separately with `uv add rcsfs`.
116
+ See [INSTALL.md](INSTALL.md) for local-wheel installation details.
117
117
 
118
118
  ## Imports
119
119
 
@@ -143,20 +143,6 @@ python -X utf8 -c "from graspkit.data_IO import MixCoefLoader; MixCoefLoader(r'p
143
143
  This option changes terminal text encoding only; it does not change how GRASP
144
144
  files are parsed.
145
145
 
146
- ## Development
147
-
148
- In the full workspace, activate the shared environment first:
149
-
150
- ```bash
151
- source ../graspkit-tools/.venv/bin/activate
152
- pytest tests/
153
- ruff check .
154
- basedpyright src/
155
- python -m build
156
- ```
157
-
158
- See [INSTALL.md](INSTALL.md) for installation details.
159
-
160
146
  ## Release preparation
161
147
 
162
148
  See [the release guide](docs/releasing.md) for local wheel/source builds and
@@ -3,8 +3,7 @@
3
3
  English | [简体中文](README_zh.md)
4
4
 
5
5
  `graspkit` is the stable foundation for reading, processing, and plotting
6
- GRASP atomic-structure calculation results. Machine-learning workflow code is
7
- owned by the sibling `graspkit-tools` repository.
6
+ GRASP atomic-structure calculation results.
8
7
 
9
8
  ## Package structure
10
9
 
@@ -17,35 +16,31 @@ owned by the sibling `graspkit-tools` repository.
17
16
  quantum-number helpers.
18
17
  - `graspkit_plot`: plotting and publication-style helpers.
19
18
 
20
- The package deliberately does not contain ML models, training configuration,
21
- or iterative pipeline state. Those live under
22
- `graspkit-tools/ml_CSFs_selection_scripts/ml_csf_choosing/`.
23
-
24
19
  ## Installation
25
20
 
26
21
  Install [graspkit-atomic from PyPI](https://pypi.org/project/graspkit-atomic/)
27
22
  with Python 3.14 or newer. The distribution name is `graspkit-atomic`;
28
23
  its Python import packages are `graspkit` and `graspkit_plot`.
29
24
 
30
- ### With pip
25
+ ### With uv
31
26
 
32
- > The new PyPI name is prepared for publication. The installation commands below
33
- > apply after the first `graspkit-atomic` release.
27
+ Use [uv](https://docs.astral.sh/uv/getting-started/installation/) to manage the
28
+ environment and dependencies of your own analysis project. For a new project:
34
29
 
35
30
  ```bash
36
- python -m pip install graspkit-atomic
31
+ uv init --python 3.14 atomic-analysis
32
+ cd atomic-analysis
33
+ uv add graspkit-atomic
34
+ uv run python -c "import graspkit; print(graspkit.__version__)"
37
35
  ```
38
36
 
39
- To reproduce the current release exactly:
37
+ For an existing uv project using Python 3.14 or newer, run `uv add graspkit-atomic`
38
+ in its directory. This records the dependency in `pyproject.toml`, updates
39
+ `uv.lock`, and installs it in the project's `.venv`. Use `uv run python analysis.py`
40
+ to run your own analysis script; manual environment activation is not required.
41
+ To pin a particular release, use `uv add "graspkit-atomic==3.4.3"`.
40
42
 
41
- ```bash
42
- python -m pip install "graspkit-atomic==3.4.1"
43
- ```
44
-
45
- ### In pyproject.toml
46
-
47
- Add the dependency to your own project's existing `[project].dependencies`.
48
- A minimal example is:
43
+ You can also add the dependency to an existing `pyproject.toml` manually:
49
44
 
50
45
  ```toml
51
46
  [project]
@@ -53,20 +48,25 @@ name = "atomic-analysis"
53
48
  version = "0.1.0"
54
49
  requires-python = ">=3.14"
55
50
  dependencies = [
56
- "graspkit-atomic==3.4.1",
51
+ "graspkit-atomic==3.4.3",
57
52
  ]
58
53
  ```
59
54
 
60
- From your consuming project's directory, install the project and its dependencies:
55
+ Then run `uv sync` in that project's directory to resolve dependencies and
56
+ synchronize its environment. Commit `pyproject.toml` and `uv.lock` alongside
57
+ your analysis code to record the dependency choices.
58
+
59
+ ### With pip
60
+
61
+ To install into an existing Python environment:
61
62
 
62
63
  ```bash
63
- python -m pip install .
64
+ python -m pip install graspkit-atomic
64
65
  ```
65
66
 
66
- Both installation methods provide the same Python API. If your project also uses
67
- rCSFs, add `"rcsfs==1.3.1"` to the same dependency list. GraspKit's package includes
68
- the plotting API; ML training and workflow orchestration belong to `graspkit-tools`.
69
- See [INSTALL.md](INSTALL.md) for local-wheel and contributor installation details.
67
+ Both methods provide the same Python API, including plotting. If your project
68
+ also uses rCSFs, add it separately with `uv add rcsfs`.
69
+ See [INSTALL.md](INSTALL.md) for local-wheel installation details.
70
70
 
71
71
  ## Imports
72
72
 
@@ -96,20 +96,6 @@ python -X utf8 -c "from graspkit.data_IO import MixCoefLoader; MixCoefLoader(r'p
96
96
  This option changes terminal text encoding only; it does not change how GRASP
97
97
  files are parsed.
98
98
 
99
- ## Development
100
-
101
- In the full workspace, activate the shared environment first:
102
-
103
- ```bash
104
- source ../graspkit-tools/.venv/bin/activate
105
- pytest tests/
106
- ruff check .
107
- basedpyright src/
108
- python -m build
109
- ```
110
-
111
- See [INSTALL.md](INSTALL.md) for installation details.
112
-
113
99
  ## Release preparation
114
100
 
115
101
  See [the release guide](docs/releasing.md) for local wheel/source builds and
@@ -2,7 +2,7 @@
2
2
 
3
3
  [English](README.md) | 简体中文
4
4
 
5
- `graspkit` 是用于读取、二次处理和绘制 GRASP 原子结构计算结果的稳定基础库。机器学习模型、训练配置和迭代筛选流程已归入同级的 `graspkit-tools` 仓库。
5
+ `graspkit` 是用于读取、二次处理和绘制 GRASP 原子结构计算结果的稳定基础库。
6
6
 
7
7
  ## 包结构
8
8
 
@@ -12,34 +12,28 @@
12
12
  - `graspkit.utils`:通用 GRASP 数据模型、环境检测和量子数工具。
13
13
  - `graspkit_plot`:绘图和出版级样式工具。
14
14
 
15
- 本仓库不再包含 ML 模型、ML 配置或迭代训练状态;这些代码位于:
16
-
17
- ```text
18
- graspkit-tools/ml_CSFs_selection_scripts/ml_csf_choosing/
19
- ```
20
-
21
15
  ## 安装
22
16
 
23
17
  使用 Python 3.14 或更新版本,从 [PyPI 安装 graspkit-atomic](https://pypi.org/project/graspkit-atomic/)。
24
18
  分发包名为 `graspkit-atomic`,Python 导入名为 `graspkit` 和 `graspkit_plot`。
25
19
 
26
- ### 使用 pip
27
-
28
- > 新 PyPI 名称尚待首次发布,以下安装命令在 `graspkit-atomic` 发布后生效。
29
-
30
- ```bash
31
- python -m pip install graspkit-atomic
32
- ```
20
+ ### 使用 uv 管理项目
33
21
 
34
- 需要固定为当前发布版本时:
22
+ 可以用 [uv](https://docs.astral.sh/uv/getting-started/installation/) 管理你自己的分析项目环境和依赖。新建项目时:
35
23
 
36
24
  ```bash
37
- python -m pip install "graspkit-atomic==3.4.1"
25
+ uv init --python 3.14 atomic-analysis
26
+ cd atomic-analysis
27
+ uv add graspkit-atomic
28
+ uv run python -c "import graspkit; print(graspkit.__version__)"
38
29
  ```
39
30
 
40
- ### 在 pyproject.toml 中声明依赖
31
+ 已有 uv 项目使用 Python 3.14 或更新版本时,直接在其目录运行 `uv add graspkit-atomic`。
32
+ 该命令会将依赖写入 `pyproject.toml`,更新 `uv.lock`,并安装到项目的 `.venv` 中。
33
+ 运行自己的分析脚本时使用 `uv run python analysis.py`,无需手动激活环境。
34
+ 需要固定版本时,使用 `uv add "graspkit-atomic==3.4.3"`。
41
35
 
42
- 将依赖加入你自己项目已有的 `[project].dependencies`。最小示例如下:
36
+ 也可以手动将依赖加入已有的 `pyproject.toml`:
43
37
 
44
38
  ```toml
45
39
  [project]
@@ -47,19 +41,23 @@ name = "atomic-analysis"
47
41
  version = "0.1.0"
48
42
  requires-python = ">=3.14"
49
43
  dependencies = [
50
- "graspkit-atomic==3.4.1",
44
+ "graspkit-atomic==3.4.3",
51
45
  ]
52
46
  ```
53
47
 
54
- 在你的使用项目目录中安装项目及其依赖:
48
+ 编辑后,在该项目目录运行 `uv sync`,完成依赖解析和环境同步。
49
+ 将 `pyproject.toml` 和 `uv.lock` 随分析代码一起保存到版本控制中,便于记录依赖版本。
50
+
51
+ ### 使用 pip
52
+
53
+ 安装到已有的 Python 环境:
55
54
 
56
55
  ```bash
57
- python -m pip install .
56
+ python -m pip install graspkit-atomic
58
57
  ```
59
58
 
60
- 两种安装方式使用相同的 Python API。如果项目同时使用 rCSFs,可在上述依赖列表中
61
- 另加 `"rcsfs==1.3.1"`。绘图 API 已包含在本包中;ML 训练和工作流编排由
62
- `graspkit-tools` 提供。本地 wheel 安装和贡献者开发环境见 [INSTALL.md](INSTALL.md)。
59
+ 两种方式提供相同的 Python API,均包含绘图功能。如果项目同时使用 rCSFs,
60
+ 可另行执行 `uv add rcsfs`。本地 wheel 安装见 [INSTALL.md](INSTALL.md)。
63
61
 
64
62
  ## 导入示例
65
63
 
@@ -88,18 +86,6 @@ python -X utf8 -c "from graspkit.data_IO import MixCoefLoader; MixCoefLoader(r'p
88
86
 
89
87
  `-X utf8` 只会调整 Python 的文本与终端输出编码,不会改变 GRASP 文件的解析方式。
90
88
 
91
- ## 开发检查
92
-
93
- 在完整工作区中,先激活共享环境:
94
-
95
- ```bash
96
- source ../graspkit-tools/.venv/bin/activate
97
- pytest tests/
98
- ruff check .
99
- basedpyright src/
100
- python -m build
101
- ```
102
-
103
89
  ## 发布准备
104
90
 
105
91
  构建、验证和手动发布工作流见[发布指南](docs/releasing.md)。
@@ -0,0 +1,201 @@
1
+ # Preparing a graspkit-atomic release
2
+
3
+ The prepared stable version is **3.4.3**. Its single source is
4
+ `src/graspkit/version.py`; Hatchling reads it through `dynamic = ["version"]`.
5
+ The local build commands below do not upload files or create Git tags.
6
+ The separate manual publishing workflow is described near the end of this guide.
7
+
8
+ ## Local build in the paired workspace
9
+
10
+ Set up or refresh the shared environment from `graspkit-tools/` with
11
+ `uv sync --extra cpu` (`--extra gpu` on a CUDA host). Then, from `graspkit/`:
12
+
13
+ ```bash
14
+ source ../graspkit-tools/.venv/bin/activate
15
+ python build_package.py --clean
16
+ ```
17
+
18
+ The helper uses the current interpreter, builds a source archive and a wheel
19
+ from that archive, runs `twine check --strict`, checks the file manifest and
20
+ metadata, and runs a wheel smoke test. Build isolation supplies Hatchling.
21
+ It never installs tools into the runtime or copies files to the Tools repo.
22
+ The obsolete `--dev` option is removed; edit the version source deliberately.
23
+ `--clean` removes only matching graspkit-atomic archives from the selected output
24
+ folder. Unknown files cause an error instead of being deleted.
25
+
26
+ Output: `dist/graspkit_atomic-3.4.3.tar.gz` and
27
+ `dist/graspkit_atomic-3.4.3-py3-none-any.whl`. An optional `--outdir PATH` selects an
28
+ empty output folder. The shell/batch wrappers select the shared Tools Python.
29
+
30
+ Equivalent individual checks:
31
+
32
+ ```bash
33
+ python -m build
34
+ python -m twine check --strict dist/*
35
+ python scripts/check_release.py dist --smoke
36
+ python -m pytest tests/
37
+ ```
38
+
39
+ Do not reuse a directory containing artifacts from other versions. The checker
40
+ prints SHA-256 hashes and rejects mixed versions, missing metadata/licenses,
41
+ unexpected archive contents and absent typing markers. The smoke test starts
42
+ a separate interpreter from a temporary directory, loads the extracted wheel,
43
+ checks its import origin and version, selects CSFs and renders a plot. Locally,
44
+ runtime dependencies come from Tools; this is not a clean dependency-resolution
45
+ test. The CI workflow installs the wheel and dependencies on a fresh runner.
46
+
47
+ ## Files and license
48
+
49
+ The wheel contains `graspkit` and `graspkit_plot`. The source archive includes
50
+ those sources, metadata, GPLv3 text and selected installation/build docs.
51
+ Research notes, agent instructions, tests, local data and historical reports
52
+ are excluded. Full regression tests remain in the development repository.
53
+ The existing GPLv3 license is recorded as `GPL-3.0-only`.
54
+
55
+ ## Build-only CI
56
+
57
+ `.github/workflows/build-release.yml` runs by manual dispatch or by an explicit
58
+ push to a `codex/release-build-check-*` branch. It is also reusable through
59
+ `workflow_call`, so the publishing workflow builds the same commit. It builds
60
+ and checks on Linux, Windows and macOS using Python 3.14, and stores GitHub
61
+ Actions artifacts. It has no PyPI credentials, OIDC publishing permission,
62
+ publish job or tag-triggered upload. CI uses an ephemeral standalone runner;
63
+ it does not create a second runtime in this paired local workspace.
64
+ A universal wheel still relies on its dependencies supporting the target OS.
65
+ Python versions above 3.14 are permitted by metadata but not yet in this matrix.
66
+
67
+ Until the workflow reaches the default branch, start a check from the release
68
+ commit by pushing it to a dedicated branch, for example:
69
+
70
+ ```bash
71
+ git push origin HEAD:refs/heads/codex/release-build-check-20261020
72
+ ```
73
+
74
+ Choose a fresh suffix for a separate run of an unchanged commit. Normal
75
+ development-branch pushes and tags do not trigger this workflow. Once the
76
+ workflow is on the default branch, the Actions page also offers **Run workflow**
77
+ with a branch selector. Review all three platform jobs before using the artifacts.
78
+
79
+ ## Before a later publication
80
+
81
+ 1. Review the exact source commit and release changes; rerun the workflow on it.
82
+ 2. Confirm PyPI ownership/availability of `graspkit-atomic`, and that version 3.4.3
83
+ has not already been published. A missing public project page alone does
84
+ not prove that a name is available.
85
+ 3. Inspect the actual archives and hashes. Publishing makes their contents
86
+ public even if the Git repository remains private. Repository URLs in the
87
+ metadata require access to that repository; provide accessible public docs
88
+ or change visibility deliberately if external users need them.
89
+ 4. Test installation from TestPyPI only when an upload is explicitly authorized.
90
+ 5. Configure the Trusted Publisher described below and run the manual
91
+ publishing workflow only when the upload is authorized.
92
+ 6. Tag the approved commit and record the version/release notes. A later commit
93
+ request also covers the parent gitlink update; this preparation creates no tag.
94
+
95
+ References: [PyPA packaging](https://packaging.python.org/en/latest/tutorials/packaging-projects/),
96
+ [Trusted Publishing](https://docs.pypi.org/trusted-publishers/).
97
+
98
+ ## Manual publishing to PyPI and GitHub
99
+
100
+ `.github/workflows/publish.yml` is named **Publish packages** in GitHub Actions.
101
+ It runs only through **Run workflow**, from `main`. Pushing commits, tags, or
102
+ completing a build does not start a publication. Its inputs are:
103
+
104
+ | Input | Default | Purpose |
105
+ | --- | --- | --- |
106
+ | `version` | Required | Exact source version, currently `3.4.3`. |
107
+ | `publish_pypi` | Off | Upload the validated packages to PyPI. |
108
+ | `github_release` | Off | Create a GitHub Release using the same packages. |
109
+ | `draft` | On | Keep the GitHub Release as a draft; turn off only for formal publication. |
110
+
111
+ Open **Actions → Publish packages → Run workflow**, select `main`, enter the
112
+ source version, and select the destinations you intend to use:
113
+
114
+ | PyPI | GitHub Release | Result |
115
+ | --- | --- | --- |
116
+ | Off | Off | Build and validate only; no publication. |
117
+ | On | Off | Build, validate and upload to PyPI. |
118
+ | Off | On | Build, validate and create a GitHub Release (draft by default). |
119
+ | On | On | Build and validate once, then upload the same files to both destinations. |
120
+
121
+ A prior dry run is optional. No separate workflow, run ID or tag input is
122
+ needed. The GitHub tag is derived as `v{version}`, for example `v3.4.3`.
123
+ The `draft` option has no effect when `github_release` is off.
124
+
125
+ ### One build, two independent destinations
126
+
127
+ Preflight checks the requested version against the source before the existing
128
+ Linux/Windows/macOS build matrix runs. The assembler checks package names,
129
+ filename/metadata versions and Python/platform tags across the full matrix.
130
+ It retains one Linux source archive, plus one universal wheel for GraspKit or
131
+ three native wheels for rCSFs. The canonical files are stored in the
132
+ **pypi-distributions** Actions artifact with SHA-256 hashes in the job summary.
133
+
134
+ Both upload jobs depend directly on the successful `prepare` job. They each
135
+ consume that same artifact and do not rebuild. Neither upload job depends on
136
+ the other: a PyPI failure does not block GitHub Release creation, and vice versa.
137
+ If an upload fails before creating a Release or accepting files, retrying that
138
+ failed job reuses the run's existing validated artifact. Resolve any existing
139
+ file/Release conflict before retrying; successful uploads are not overwritten.
140
+ The workflow has no rollback across services; inspect each job's result.
141
+ The concurrency group serializes runs of this publishing workflow.
142
+
143
+ A dry run (both destination options off) does not exercise PyPI authorization.
144
+ PyPI uploads only work for filenames that have not already been used. For a
145
+ new release of modified package contents, update the source version and enter
146
+ that version in the workflow; do not try to overwrite an existing release.
147
+
148
+ ### GitHub Release behavior
149
+
150
+ The Release job automatically reads this run's ID, attempt and source commit
151
+ from GitHub. It confirms that preflight, all three builds and preparation have
152
+ succeeded; it does not require the whole workflow or the PyPI job to finish.
153
+ It checks the downloaded artifact's GitHub SHA-256 digest, package metadata and
154
+ wheel platforms before creating a Release. These checks run with Python's
155
+ standard library and the GitHub CLI supplied by the hosted runner.
156
+
157
+ The Release contains the wheel(s), source archive and `SHA256SUMS`. Its notes
158
+ record the exact source commit, build-run URL, artifact ID and per-file hashes.
159
+ An existing tag must resolve to that commit; an existing Release for the same
160
+ tag, including a draft, causes a failure instead of being overwritten. Partial
161
+ drafts are retained for inspection. Review drafts in the repository's
162
+ **Releases** page. When a tag does not exist yet, GitHub may defer creating it
163
+ until the draft is published; the draft retains the exact target commit.
164
+
165
+ The default is a **draft**. Formal GitHub publication happens only when
166
+ `github_release` is on and `draft` is explicitly off. The Release job uses the
167
+ built-in `GITHUB_TOKEN` with `actions: read` and `contents: write`; it needs no
168
+ personal access token, PyPI credential or OIDC permission.
169
+
170
+ ### PyPI authorization
171
+
172
+ Only the `publish_pypi` job uses the `pypi` environment and `id-token: write`.
173
+ It downloads the prepared artifact and invokes `pypa/gh-action-pypi-publish`.
174
+ The workflow filename is still `publish.yml`; changing its display name to
175
+ **Publish packages** does not change the Trusted Publisher identity.
176
+
177
+ 1. In this GitHub repository, open **Settings → Environments** and ensure an
178
+ environment named exactly `pypi` exists. No PyPI API token is needed.
179
+ 2. For an existing PyPI project you own, open its **Publishing** settings and
180
+ add or verify the GitHub Trusted Publisher. For a new project, use
181
+ [account Publishing](https://pypi.org/manage/account/publishing/) to add a
182
+ pending publisher instead:
183
+
184
+ | PyPI field | Value |
185
+ | --- | --- |
186
+ | PyPI Project Name (pending publisher only) | `graspkit-atomic` |
187
+ | Owner | `YenochQin` |
188
+ | Repository name | `graspkit` |
189
+ | Workflow name | `publish.yml` |
190
+ | Environment name | `pypi` |
191
+
192
+ Enter only the workflow filename, without `.github/workflows/`. A pending
193
+ publisher does not reserve the project name; the first successful use
194
+ creates the project. Authorization for another PyPI project does not
195
+ automatically authorize this one.
196
+ 3. To rehearse, leave **publish_pypi** and **github_release** unchecked. To upload
197
+ to PyPI when authorized, enable **publish_pypi**. Enable **github_release**
198
+ too if you also want the same files on GitHub, leaving **draft** checked
199
+ unless a formal Release is intended. This workflow has no TestPyPI target.
200
+
201
+ See the [PyPI Trusted Publishing guide](https://docs.pypi.org/trusted-publishers/).
@@ -1,3 +1,3 @@
1
1
  """Package version, also read by Hatchling when building distributions."""
2
2
 
3
- __version__ = "3.4.1"
3
+ __version__ = "3.4.3"
@@ -1,79 +0,0 @@
1
- # Installation
2
-
3
- `graspkit-atomic` requires Python 3.14 or newer. It provides the `graspkit` and
4
- `graspkit_plot` import packages. The distribution name is changing from `grasp-atomic-kit` to `graspkit-atomic`;
5
- existing import statements need no changes. The commands below apply after the
6
- first release under the new name. For existing projects, replace the old
7
- dependency rather than declaring both distributions, which provide the same
8
- Python packages.
9
-
10
- ## Install from PyPI
11
-
12
- ```bash
13
- python -m pip install graspkit-atomic
14
- ```
15
-
16
- For a fixed release:
17
-
18
- ```bash
19
- python -m pip install "graspkit-atomic==3.4.1"
20
- ```
21
-
22
- ## Declare a project dependency
23
-
24
- Add `"graspkit-atomic==3.4.1"` to the existing `[project].dependencies` list in
25
- your own `pyproject.toml`. A minimal example:
26
-
27
- ```toml
28
- [project]
29
- name = "atomic-analysis"
30
- version = "0.1.0"
31
- requires-python = ">=3.14"
32
- dependencies = ["graspkit-atomic==3.4.1"]
33
- ```
34
-
35
- Install your consuming project and its dependencies from its directory with
36
- `python -m pip install .`. Add `"rcsfs==1.3.1"` to the dependency list separately
37
- if your application also needs the Rust CSF library.
38
-
39
- Pip installs the declared runtime dependencies; Rust and the GRASP executables
40
- are not needed to install this Python library. Reading calculation results
41
- requires the corresponding GRASP data files.
42
-
43
- ## Local wheel or source installation
44
-
45
- To install a downloaded wheel, use its exact filename:
46
-
47
- ```bash
48
- python -m pip install /path/to/graspkit_atomic-3.4.1-py3-none-any.whl
49
- ```
50
-
51
- A standalone source checkout also supports `python -m pip install .`.
52
-
53
- ## Full workspace development
54
-
55
- Use the environment owned by Tools. Run setup from `graspkit-tools/` only:
56
-
57
- ```bash
58
- cd ../graspkit-tools
59
- uv sync --extra cpu
60
- source .venv/bin/activate
61
- python -c "import graspkit; print(graspkit.__version__)"
62
- ```
63
-
64
- Select `--extra gpu` instead on a CUDA host. On Windows activate
65
- `.venv\Scripts\activate` after syncing. Tools installs GraspKit as an editable
66
- path dependency; ordinary Python edits are immediately visible. Do not install
67
- release wheels into this shared environment for testing: the release checker
68
- loads an unpacked wheel in a disposable directory instead.
69
-
70
- ## Verification
71
-
72
- ```bash
73
- python -c "from graspkit.data_IO import EnergyFileLoader; print(EnergyFileLoader)"
74
- python -c "import graspkit_plot; print(graspkit_plot.__file__)"
75
- ```
76
-
77
- For builds and artifact tests, see [the release guide](docs/releasing.md).
78
- PyTorch, scikit-learn and training workflows belong to `graspkit-tools` and
79
- are not dependencies of this library.
@@ -1,156 +0,0 @@
1
- # Preparing a graspkit-atomic release
2
-
3
- The prepared stable version is **3.4.1**. Its single source is
4
- `src/graspkit/version.py`; Hatchling reads it through `dynamic = ["version"]`.
5
- The local build commands below do not upload files or create Git tags.
6
- The separate manual publishing workflow is described near the end of this guide.
7
-
8
- ## Local build in the paired workspace
9
-
10
- Set up or refresh the shared environment from `graspkit-tools/` with
11
- `uv sync --extra cpu` (`--extra gpu` on a CUDA host). Then, from `graspkit/`:
12
-
13
- ```bash
14
- source ../graspkit-tools/.venv/bin/activate
15
- python build_package.py --clean
16
- ```
17
-
18
- The helper uses the current interpreter, builds a source archive and a wheel
19
- from that archive, runs `twine check --strict`, checks the file manifest and
20
- metadata, and runs a wheel smoke test. Build isolation supplies Hatchling.
21
- It never installs tools into the runtime or copies files to the Tools repo.
22
- The obsolete `--dev` option is removed; edit the version source deliberately.
23
- `--clean` removes only matching graspkit-atomic archives from the selected output
24
- folder. Unknown files cause an error instead of being deleted.
25
-
26
- Output: `dist/graspkit_atomic-3.4.1.tar.gz` and
27
- `dist/graspkit_atomic-3.4.1-py3-none-any.whl`. An optional `--outdir PATH` selects an
28
- empty output folder. The shell/batch wrappers select the shared Tools Python.
29
-
30
- Equivalent individual checks:
31
-
32
- ```bash
33
- python -m build
34
- python -m twine check --strict dist/*
35
- python scripts/check_release.py dist --smoke
36
- python -m pytest tests/
37
- ```
38
-
39
- Do not reuse a directory containing artifacts from other versions. The checker
40
- prints SHA-256 hashes and rejects mixed versions, missing metadata/licenses,
41
- unexpected archive contents and absent typing markers. The smoke test starts
42
- a separate interpreter from a temporary directory, loads the extracted wheel,
43
- checks its import origin and version, selects CSFs and renders a plot. Locally,
44
- runtime dependencies come from Tools; this is not a clean dependency-resolution
45
- test. The CI workflow installs the wheel and dependencies on a fresh runner.
46
-
47
- ## Files and license
48
-
49
- The wheel contains `graspkit` and `graspkit_plot`. The source archive includes
50
- those sources, metadata, GPLv3 text and selected installation/build docs.
51
- Research notes, agent instructions, tests, local data and historical reports
52
- are excluded. Full regression tests remain in the development repository.
53
- The existing GPLv3 license is recorded as `GPL-3.0-only`.
54
-
55
- ## Build-only CI
56
-
57
- `.github/workflows/build-release.yml` runs by manual dispatch or by an explicit
58
- push to a `codex/release-build-check-*` branch. It is also reusable through
59
- `workflow_call`, so the publishing workflow builds the same commit. It builds
60
- and checks on Linux, Windows and macOS using Python 3.14, and stores GitHub
61
- Actions artifacts. It has no PyPI credentials, OIDC publishing permission,
62
- publish job or tag-triggered upload. CI uses an ephemeral standalone runner;
63
- it does not create a second runtime in this paired local workspace.
64
- A universal wheel still relies on its dependencies supporting the target OS.
65
- Python versions above 3.14 are permitted by metadata but not yet in this matrix.
66
-
67
- Until the workflow reaches the default branch, start a check from the release
68
- commit by pushing it to a dedicated branch, for example:
69
-
70
- ```bash
71
- git push origin HEAD:refs/heads/codex/release-build-check-20261020
72
- ```
73
-
74
- Choose a fresh suffix for a separate run of an unchanged commit. Normal
75
- development-branch pushes and tags do not trigger this workflow. Once the
76
- workflow is on the default branch, the Actions page also offers **Run workflow**
77
- with a branch selector. Review all three platform jobs before using the artifacts.
78
-
79
- ## Before a later publication
80
-
81
- 1. Review the exact source commit and release changes; rerun the workflow on it.
82
- 2. Confirm PyPI ownership/availability of `graspkit-atomic`, and that version 3.4.1
83
- has not already been published. A missing public project page alone does
84
- not prove that a name is available.
85
- 3. Inspect the actual archives and hashes. Publishing makes their contents
86
- public even if the Git repository remains private. Repository URLs in the
87
- metadata require access to that repository; provide accessible public docs
88
- or change visibility deliberately if external users need them.
89
- 4. Test installation from TestPyPI only when an upload is explicitly authorized.
90
- 5. Configure the Trusted Publisher described below and run the manual
91
- publishing workflow only when the upload is authorized.
92
- 6. Tag the approved commit and record the version/release notes. A later commit
93
- request also covers the parent gitlink update; this preparation creates no tag.
94
-
95
- References: [PyPA packaging](https://packaging.python.org/en/latest/tutorials/packaging-projects/),
96
- [Trusted Publishing](https://docs.pypi.org/trusted-publishers/).
97
-
98
- ## Manual PyPI publishing
99
-
100
- `.github/workflows/publish.yml` is named **Publish to PyPI** in GitHub Actions.
101
- It has only a `workflow_dispatch` trigger. Pushing commits, tags, or completing
102
- an ordinary build does not start it. It accepts two inputs:
103
-
104
- - `version`: the exact version in the source, currently `3.4.1`.
105
- - `publish`: a checkbox, **false by default**. Leave it unchecked for a dry run.
106
-
107
- Only `main` is accepted. Preflight checks the requested version before the
108
- existing three-platform build matrix runs. The assembler validates every
109
- platform's package name, filename/metadata version and Python/platform tags,
110
- then retains one canonical Linux source archive. GraspKit keeps only the Linux
111
- copy of its universal wheel; rCSFs keeps all three platform wheels. This avoids
112
- silently overwriting duplicate filenames from different runners.
113
-
114
- The prepared archives are stored in the **pypi-distributions** Actions artifact;
115
- the job summary lists their SHA-256 hashes and source commit. Preparation and
116
- build jobs have no OIDC permission. Only the final, separately gated `publish`
117
- job uses the `pypi` environment and `id-token: write`. That job downloads the
118
- prepared artifact and invokes `pypa/gh-action-pypi-publish`; it does not rebuild.
119
- When `publish` is false, the upload job is skipped entirely. The workflow group
120
- serializes publication attempts. It neither bumps versions nor creates tags.
121
-
122
- ### Configure authorization in the browser
123
-
124
- This rename creates a new PyPI project, `graspkit-atomic`. Authorization for the
125
- previous `grasp-atomic-kit` project does not carry over; configure the publisher
126
- for the new name below. The repository and Python import names stay unchanged.
127
-
128
- 1. In this GitHub repository, open **Settings → Environments → New environment**
129
- and create an environment named exactly **pypi**. No PyPI token or environment
130
- secret is needed. You can restrict its deployment branches to `main`.
131
- 2. Log in to [PyPI Publishing](https://pypi.org/manage/account/publishing/).
132
- Under **Add a new pending publisher**, choose **GitHub** and enter:
133
-
134
- | PyPI field | Value |
135
- | --- | --- |
136
- | PyPI Project Name | `graspkit-atomic` |
137
- | Owner | `YenochQin` |
138
- | Repository name | `graspkit` |
139
- | Workflow name | `publish.yml` |
140
- | Environment name | `pypi` |
141
-
142
- Enter only `publish.yml`, without `.github/workflows/`. The owner is the
143
- GitHub account name, not the PyPI username. Add the pending publisher. This
144
- does not upload files, create the project or reserve its name; the project
145
- is created on the first successful publication. If you already own an
146
- existing project with this name, add the publisher in that project's
147
- Publishing settings instead.
148
- 3. For a rehearsal, choose **Actions → Publish to PyPI → Run workflow**, select
149
- `main`, enter `3.4.1` and leave **publish unchecked**. All builds and
150
- package checks run, and the upload job is skipped. A dry run does not test
151
- the PyPI OIDC exchange because it never enters the publishing job.
152
- 4. Only when publication is authorized, run the same workflow from `main` with
153
- the exact version and **publish checked**. Then install that version from
154
- PyPI to verify it. TestPyPI is not a destination in this production workflow.
155
-
156
- The pending-publisher setup follows the [PyPI guide](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
File without changes