graspkit-atomic 3.4.1__tar.gz → 3.4.2__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.

Potentially problematic release.


This version of graspkit-atomic might be problematic. Click here for more details.

Files changed (50) hide show
  1. graspkit_atomic-3.4.2/INSTALL.md +63 -0
  2. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/PKG-INFO +27 -41
  3. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/README.md +26 -40
  4. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/README_zh.md +22 -36
  5. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/docs/releasing.md +36 -6
  6. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/version.py +1 -1
  7. graspkit_atomic-3.4.1/INSTALL.md +0 -79
  8. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/.gitignore +0 -0
  9. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/LICENSE +0 -0
  10. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/build_package.py +0 -0
  11. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/pyproject.toml +0 -0
  12. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/scripts/check_release.py +0 -0
  13. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/CSFs_processor/__init__.py +0 -0
  14. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/CSFs_processor/coupling.py +0 -0
  15. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/CSFs_processor/extraction.py +0 -0
  16. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/CSFs_processor/selection.py +0 -0
  17. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/CSFs_processor/validation.py +0 -0
  18. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/__init__.py +0 -0
  19. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/__init__.py +0 -0
  20. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/file_locator.py +0 -0
  21. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/loaders/__init__.py +0 -0
  22. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/loaders/base_loader.py +0 -0
  23. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/loaders/binary_file_loader.py +0 -0
  24. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/loaders/energy_file_loader.py +0 -0
  25. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/loaders/gj_factor_loader.py +0 -0
  26. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/loaders/hyperfine_structure_loader.py +0 -0
  27. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/loaders/lsj_comp_loader.py +0 -0
  28. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/loaders/mix_coef_loader.py +0 -0
  29. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/loaders/radial_analysis_loader.py +0 -0
  30. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/loaders/radial_wavefunction_loader.py +0 -0
  31. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/loaders/transition_loader.py +0 -0
  32. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/mix_coef_writer.py +0 -0
  33. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/data_IO/produced_data_writor.py +0 -0
  34. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/grasp_data_extractor/__init__.py +0 -0
  35. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/grasp_data_extractor/asfs_data_processor.py +0 -0
  36. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/grasp_data_extractor/radial_analysis.py +0 -0
  37. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/grasp_data_extractor/radial_wavefunction_processor.py +0 -0
  38. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/grasp_data_extractor/rmix_data_processor.py +0 -0
  39. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/grasp_data_extractor/transition_data_processor.py +0 -0
  40. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/py.typed +0 -0
  41. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/utils/__init__.py +0 -0
  42. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/utils/data_modules.py +0 -0
  43. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/utils/environment_config.py +0 -0
  44. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/utils/quadrupole_deformation.py +0 -0
  45. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit/utils/tool_function.py +0 -0
  46. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit_plot/__init__.py +0 -0
  47. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit_plot/fig_settings.py +0 -0
  48. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit_plot/mid_coupling.py +0 -0
  49. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/src/graspkit_plot/plot_functions.py +0 -0
  50. {graspkit_atomic-3.4.1 → graspkit_atomic-3.4.2}/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.2"
19
+ ```
20
+
21
+ ## Declare a project dependency
22
+
23
+ Add `"graspkit-atomic==3.4.2"` 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.2"]
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.2-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.2
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.2"`.
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.2",
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.2"`.
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.2",
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.2"`。
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.2",
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)。
@@ -1,6 +1,6 @@
1
1
  # Preparing a graspkit-atomic release
2
2
 
3
- The prepared stable version is **3.4.1**. Its single source is
3
+ The prepared stable version is **3.4.2**. Its single source is
4
4
  `src/graspkit/version.py`; Hatchling reads it through `dynamic = ["version"]`.
5
5
  The local build commands below do not upload files or create Git tags.
6
6
  The separate manual publishing workflow is described near the end of this guide.
@@ -23,8 +23,8 @@ The obsolete `--dev` option is removed; edit the version source deliberately.
23
23
  `--clean` removes only matching graspkit-atomic archives from the selected output
24
24
  folder. Unknown files cause an error instead of being deleted.
25
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
26
+ Output: `dist/graspkit_atomic-3.4.2.tar.gz` and
27
+ `dist/graspkit_atomic-3.4.2-py3-none-any.whl`. An optional `--outdir PATH` selects an
28
28
  empty output folder. The shell/batch wrappers select the shared Tools Python.
29
29
 
30
30
  Equivalent individual checks:
@@ -79,7 +79,7 @@ with a branch selector. Review all three platform jobs before using the artifact
79
79
  ## Before a later publication
80
80
 
81
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
82
+ 2. Confirm PyPI ownership/availability of `graspkit-atomic`, and that version 3.4.2
83
83
  has not already been published. A missing public project page alone does
84
84
  not prove that a name is available.
85
85
  3. Inspect the actual archives and hashes. Publishing makes their contents
@@ -101,7 +101,7 @@ References: [PyPA packaging](https://packaging.python.org/en/latest/tutorials/pa
101
101
  It has only a `workflow_dispatch` trigger. Pushing commits, tags, or completing
102
102
  an ordinary build does not start it. It accepts two inputs:
103
103
 
104
- - `version`: the exact version in the source, currently `3.4.1`.
104
+ - `version`: the exact version in the source, currently `3.4.2`.
105
105
  - `publish`: a checkbox, **false by default**. Leave it unchecked for a dry run.
106
106
 
107
107
  Only `main` is accepted. Preflight checks the requested version before the
@@ -146,7 +146,7 @@ for the new name below. The repository and Python import names stay unchanged.
146
146
  existing project with this name, add the publisher in that project's
147
147
  Publishing settings instead.
148
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
149
+ `main`, enter `3.4.2` and leave **publish unchecked**. All builds and
150
150
  package checks run, and the upload job is skipped. A dry run does not test
151
151
  the PyPI OIDC exchange because it never enters the publishing job.
152
152
  4. Only when publication is authorized, run the same workflow from `main` with
@@ -154,3 +154,33 @@ for the new name below. The repository and Python import names stay unchanged.
154
154
  PyPI to verify it. TestPyPI is not a destination in this production workflow.
155
155
 
156
156
  The pending-publisher setup follows the [PyPI guide](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
157
+
158
+ ## GitHub Release drafts from a successful rehearsal
159
+
160
+ Open **Actions → Draft GitHub Release → Run workflow** and select `main`.
161
+ Fill in `run_id` with the numeric ID from a successful **Publish to PyPI**
162
+ rehearsal URL (`/actions/runs/NUMBER`), and `tag` with `v3.4.2` (or the
163
+ version of that rehearsal). The selected run must have `publish` unchecked:
164
+ `preflight`, all three builds and `prepare` must pass, and `publish` must be
165
+ skipped. Runs from forks, other workflows or branches are rejected.
166
+
167
+ The workflow downloads that run's unexpired `pypi-distributions` artifact,
168
+ checks its GitHub SHA-256 digest, and verifies package names, metadata versions
169
+ and the expected wheel platforms. It reuses the exact archives without
170
+ installing dependencies or rebuilding. The script uses Python's standard
171
+ library and the GitHub CLI supplied by the hosted runner.
172
+
173
+ The resulting **draft** contains the wheel(s), source archive and `SHA256SUMS`.
174
+ Its notes record the source commit, run URL, artifact ID and per-file hashes.
175
+ The Release target is the rehearsal's commit, even if `main` has moved since.
176
+ An existing tag must resolve to that commit; an existing Release for the tag
177
+ (including a draft) causes a failure instead of overwriting it. Failed partial
178
+ drafts are retained for inspection. If an artifact has expired, run a new
179
+ rehearsal and use its run ID.
180
+
181
+ This workflow always creates a draft: it has no formal-publication switch and
182
+ no PyPI job or OIDC permission. It needs only the built-in `GITHUB_TOKEN` with
183
+ `actions: read` and `contents: write`, not a personal token or PyPI secret.
184
+ Review the draft in **Releases**; publishing it later requires a separate
185
+ manual action. If the tag does not exist yet, GitHub may defer creating it
186
+ until the draft is published; the draft retains the exact target commit.
@@ -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.2"
@@ -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.
File without changes