Lrc

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11"]
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -W error::ResourceWarning -m unittest discover -s tests
+
+      - name: Compile sources
+        run: python -m compileall groupy tests scripts
+
+      - name: Build Python package
+        run: python -m build
+
+      - name: Check Windows app build command
+        run: python scripts/build_windows_app.py --dry-run

.gitignore

@@ -9,6 +9,7 @@ __pycache__/
 # Distribution / packaging
 .Python
 build/
+build_check_dist/
 develop-eggs/
 dist/
 downloads/

PACKAGING_SIZE_REPORT.md

@@ -0,0 +1,125 @@
+# Groupy Packaging Size Report
+
+Created: 2026-06-25
+
+This report records the packaged Windows app size baseline and the result after rebuilding from a clean OpenBLAS-based packaging environment.
+
+## Current Baseline
+
+Measured artifact:
+
+```text
+dist/Groupy/Groupy.exe
+dist/Groupy/_internal
+```
+
+Overall size:
+
+| Path | Size |
+| --- | ---: |
+| `dist/Groupy` | 772.41 MB |
+| `dist/Groupy/_internal` | 753.50 MB |
+| `dist/Groupy/Groupy.exe` | 18.91 MB |
+
+Top component groups:
+
+| Component | Count | Size |
+| --- | ---: | ---: |
+| MKL DLLs | 25 | 538.61 MB |
+| ICU DLLs | 12 | 46.96 MB |
+| RDKit package and DLLs | 244 | 35.63 MB |
+| Qt DLLs | 5 | 22.53 MB |
+| PySide6 package | 121 | 22.34 MB |
+| pandas package | 53 | 12.50 MB |
+| matplotlib package | 211 | 11.22 MB |
+| numpy package | 13 | 5.87 MB |
+| Tcl/Tk files | 7 | 3.44 MB |
+
+Largest files:
+
+| File | Size |
+| --- | ---: |
+| `mkl_avx512.3.dll` | 71.92 MB |
+| `mkl_core.3.dll` | 68.57 MB |
+| `mkl_avx10.3.dll` | 64.55 MB |
+| `mkl_avx2.3.dll` | 45.28 MB |
+| `mkl_mc3.3.dll` | 44.96 MB |
+| `mkl_intel_thread.3.dll` | 37.27 MB |
+| `mkl_def.3.dll` | 35.34 MB |
+| `icudt78.dll` | 31.58 MB |
+| `mkl_tbb_thread.3.dll` | 28.46 MB |
+| `mkl_rt.3.dll` | 26.60 MB |
+
+## OpenBLAS Rebuild Result
+
+Measured after rebuilding from a clean conda-forge packaging environment with OpenBLAS-linked numerical dependencies.
+
+Overall size:
+
+| Path | Size |
+| --- | ---: |
+| `dist/Groupy` | 228.43 MB |
+| `dist/Groupy/_internal` | 213.04 MB |
+| `dist/Groupy/Groupy.exe` | 15.39 MB |
+
+Top component groups:
+
+| Component | Count | Size |
+| --- | ---: | ---: |
+| ICU DLLs | 3 | 38.21 MB |
+| RDKit package and DLLs | 244 | 35.63 MB |
+| OpenBLAS/BLAS DLLs | 3 | 27.32 MB |
+| Qt DLLs | 5 | 22.53 MB |
+| PySide6 package | 120 | 22.24 MB |
+| pandas package | 53 | 12.50 MB |
+| numpy package | 13 | 5.87 MB |
+| matplotlib package | 0 | 0.00 MB |
+| MKL DLLs | 0 | 0.00 MB |
+
+Largest files:
+
+| File | Size |
+| --- | ---: |
+| `icudt78.dll` | 31.58 MB |
+| `openblas.dll` | 27.04 MB |
+| `Qt6Gui.dll` | 8.45 MB |
+| `libcrypto-3-x64.dll` | 7.08 MB |
+| `Qt6Widgets.dll` | 6.24 MB |
+| `python311.dll` | 5.91 MB |
+| `Qt6Core.dll` | 5.55 MB |
+
+Reduction compared with the MKL-linked baseline:
+
+| Path | Before | After | Reduction |
+| --- | ---: | ---: | ---: |
+| `dist/Groupy` | 772.41 MB | 228.43 MB | 543.98 MB |
+| `dist/Groupy/_internal` | 753.50 MB | 213.04 MB | 540.46 MB |
+| `dist/Groupy/Groupy.exe` | 18.91 MB | 15.39 MB | 3.52 MB |
+
+## Interpretation
+
+- MKL is the dominant size source, accounting for about 538.61 MB.
+- Qt/PySide6 is required by the desktop GUI and accounts for about 44.87 MB before Qt transitive DLLs such as ICU.
+- RDKit is required by property calculation, group counting, and 2D structure preview.
+- `matplotlib` appears in the current `_internal` even though the build script excludes it by default. This likely means the measured `dist/Groupy` folder contains stale files from an older build or an over-collected RDKit subtree.
+- Rebuilding from a clean OpenBLAS-based packaging environment removed MKL and stale `matplotlib` contents. The current optimized artifact is about 228.43 MB and has been confirmed to run normally by the user.
+
+## Optimization Order
+
+1. Keep using the clean conda-forge packaging environment for release builds.
+2. Retest `dist/Groupy/Groupy.exe` after every packaging change.
+3. If more reduction is needed, investigate ICU, RDKit, Qt/PySide6, and Tcl/Tk in that order.
+4. If RDKit is still over-collected, replace broad `--collect-submodules=rdkit` with a narrower set of required RDKit modules and retest.
+
+## Commands
+
+Recommended clean packaging environment:
+
+```powershell
+conda create -n groupy_package -c conda-forge python=3.11 rdkit pandas numpy openpyxl tqdm joblib pyside6 pyinstaller "libblas=*=*openblas"
+conda activate groupy_package
+python -m pip install -e . --no-deps
+python scripts\build_windows_app.py
+```
+
+The build script removes `dist/Groupy` before a default onedir build. Use `--no-clean-dist` only when debugging PyInstaller behavior and stale output files are acceptable.

README.md

@@ -12,18 +12,96 @@ One may create an environment using Anaconda:
 
 `conda activate groupy_env`
 
-Install:
+Install for development:
 
-`pip install .\Groupy\dist\groupy-3.0.0.tar.gz`
+`python -m pip install -e .`
 
-`conda install -c conda-forge openbabel`(**Do not** use `pip install openbabel` )
+Install visualization support when needed:
 
-Then one can enter `Groupy` in terminal to start the Groupy.
+`python -m pip install -e ".[viewer]"`
 
-### Manual and Documention
-The user manual is in the manual folder, and the API documentation can be found in the doc folder.
+Install desktop GUI support when needed:
+
+`python -m pip install -e ".[gui]"`
+
+Install Windows app packaging support when needed:
+
+`python -m pip install -e ".[gui,package]"`
+
+Install conversion and Gaussian input generation support when needed:
+
+`conda install -c conda-forge openbabel` (**Do not** use `pip install openbabel`.)
+
+Then one can enter `Groupy` in terminal to start Groupy.
+OpenBabel is only required for conversion and Gaussian input generation workflows.
+ASE is only required for molecular visualization workflows.
+
+For non-interactive use, one can run commands such as:
+
+`Groupy count --smiles C1CCCC1`
+
+`Groupy calculate --smiles C1CCCC1`
+
+`Groupy convert --input molecule.xyz --from xyz --to mol2 --output molecule.mol2`
+
+To launch the desktop GUI after installing GUI support:
+
+`Groupy-GUI`
+
+The GUI supports SMILES text input, SMILES file import, 2D structure preview, property calculation, group counting, calculation/counting options, and CSV export.
+
+To build a double-clickable Windows app folder:
+
+`python scripts/build_windows_app.py`
+
+The default build output is `dist/Groupy/Groupy.exe`. Use `--mode onefile` to build a single executable.
+
+For a smaller package, build from a clean packaging environment instead of a broad development environment:
+
+```powershell
+conda create -n groupy_package -c conda-forge python=3.11 rdkit pandas numpy openpyxl tqdm joblib pyside6 pyinstaller
+conda activate groupy_package
+python -m pip install -e . --no-deps
+python scripts\build_windows_app.py
+```
+
+The `_internal` folder contains bundled runtime libraries. Large MKL or BLAS DLLs usually come from the build environment and should not be deleted manually unless the packaged app is retested. Build from the clean conda-forge OpenBLAS packaging environment in `PACKAGING_SIZE_REPORT.md` to avoid bundling Intel MKL.
+The build script removes the previous output folder before building so stale `_internal` files do not affect package-size checks. Use `--no-clean-dist` only for debugging.
+Current packaging-size findings and optimization order are tracked in `PACKAGING_SIZE_REPORT.md`.
+
+Before distributing a packaged app to ordinary users, follow `RELEASE_CHECKLIST.md`.
+
+The desktop app is intended for ordinary users who need SMILES-based property calculation, group counting, and CSV export. Optional workflows have separate dependency requirements:
+
+- Conversion and Gaussian input generation require OpenBabel from conda-forge and are not part of the default GUI workflow.
+- Molecular visualization requires `.[viewer]` and ASE.
+- A packaged Windows app should be tested on a clean Windows machine before distribution.
+- Package size optimization is intentionally deferred until the user-facing workflow is stable, because removing runtime DLLs without retesting can break the executable.
+
+For Python scripts or GUI integrations, use quiet batch calls:
+
+```python
+from groupy.gp_calculator import Calculator
+from groupy.gp_counter import Counter
+
+Calculator().calculate_mols("SMILES.txt", "calculate.csv", verbose=False)
+Counter().count_mols("SMILES.txt", "count.csv", add_smiles=True, verbose=False)
+```
+
+Batch APIs keep processing failed molecules by default for backward compatibility. Pass `continue_on_error=False` when a script or GUI workflow should stop at the first invalid input.
+
+CI runs the smoke tests, source compilation check, `python -m build`, and a dry-run Windows app packaging command.
+
+### Manual and Documentation
+
+Current user manuals:
+
+- Chinese: `manual/USER_MANUAL_zh.md`
+- English: `manual/USER_MANUAL_en.md`
+
+The older background-oriented manual remains in `manual/Groupy_manual.md`. Generated API documentation can be found in the doc folder and should be kept separate from source documentation.
 
 
 # Known limitation
 when calculating properties of molecules, *simultaneous* type parameters may lead to some mistake results, so we set the 
-default parameter type is *stepwise*
+default parameter type is *stepwise*