linecat 0.9.0__tar.gz

linecat-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025–2026 Vahid Anari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

linecat-0.9.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: linecat
+Version: 0.9.0
+Summary: Line Catalog Explorer: filter CDMS spectral line catalogs and draw energy-level diagrams
+Author-email: Vahid Anari <vahid.anari8@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vahid-anari/linecat
+Project-URL: Source, https://github.com/vahid-anari/linecat
+Project-URL: Issues, https://github.com/vahid-anari/linecat/issues
+Project-URL: Changelog, https://github.com/vahid-anari/linecat/blob/main/CHANGELOG.md
+Keywords: spectroscopy,CDMS,line catalog,molecular lines,energy-level diagram,astronomy,PySide6
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PySide6>=6.5
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: sciwidgets[table]~=0.10.4
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# linecat
+
+[![tests](https://github.com/vahid-anari/linecat/actions/workflows/tests.yml/badge.svg)](https://github.com/vahid-anari/linecat/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/linecat)](https://pypi.org/project/linecat/)
+[![Python](https://img.shields.io/pypi/pyversions/linecat)](https://pypi.org/project/linecat/)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+**linecat** (Line Catalog Explorer) is a desktop viewer for spectral line catalogs
+such as [CDMS](https://cdms.astro.uni-koeln.de/). It loads a catalog converted
+to CSV, filters the transitions by frequency range and by the quantum numbers of
+the upper and lower states, shows the result in a table, exports the selection,
+and draws an interactive energy-level diagram of the selected transitions
+(with secondary transitions, hover information and a LaTeX/TikZ export).
+
+Supported species: OH, CH3OH, SiO, NH3. Adding a species means adding its
+quantum-number rules to `linecat/molecules.py`.
+
+<img src="https://raw.githubusercontent.com/vahid-anari/linecat/main/docs/figures/main_window.png" width="700" alt="linecat main window: quantum-number filters, frequency range and the table of OH lines">
+
+<img src="https://raw.githubusercontent.com/vahid-anari/linecat/main/docs/figures/diagram.png" width="700" alt="Energy-level diagram of the selected OH transitions with the transition table">
+
+## Installation
+
+Python 3.10 or newer. With [pipx](https://pipx.pypa.io/) (its own environment, recommended):
+
+```
+pipx install linecat
+```
+
+or with pip, in an environment of your choice:
+
+```
+pip install linecat
+```
+
+To start it with a double-click, run once:
+
+```
+linecat install-app
+```
+
+This adds Line Catalog Explorer to your Applications folder (macOS), the Start menu
+(Windows) or the applications menu (Linux), with its own icon. It starts the linecat
+of the Python you ran the command with, and keeps working after updates.
+
+To update, use Help → Check for Updates… in the app (it also checks quietly at
+start-up) or `linecat update` in a terminal.
+
+For development, install from a clone: `git clone https://github.com/vahid-anari/linecat.git`,
+then `pip install -e ".[dev]"` in the folder; such a copy is updated with `git pull`.
+
+## Use
+
+```
+linecat                       open the viewer
+linecat my_catalog.csv        open a catalog at start
+linecat convert               convert the shipped CDMS files into the current folder
+linecat convert OH --catalogs my_cats --output-dir out   convert your own .cat files
+linecat update                update from PyPI (asks first; --check only looks)
+linecat install-app           add the app to Applications / Start menu (--remove to undo)
+linecat --version
+```
+
+File → Open Built-in Catalog → OH / CH3OH / SiO / NH3 (⌘1–⌘4) opens a
+catalog that ships with linecat; File → Open Catalog… loads any other CSV; the quantum-number filters and the
+frequency range narrow the table; File → Export Table as CSV… writes what is
+shown; Transitions → Show Energy-Level Diagram draws the selected lines
+(hover for ν and τ, double-click a transition for the lines from its lower
+level). Right-click a column header for colours, alignment, font and columns.
+
+## Catalogs
+
+linecat ships, for OH, CH3OH, SiO and NH3, the CDMS `.cat` files, the CDMS
+documentation of each entry (PDF) and a picture of the molecule, one folder per
+species (`src/linecat/data/molecules/<SPECIES>/`); the main window shows them in
+its Molecule box, and Help → CDMS Documentation opens the general CDMS
+documents. On first start, and after every linecat update, it
+converts them to read-only CSV files in the application-data folder
+(macOS: `~/Library/Application Support/linecat/catalogs/`; File → Show
+Built-in Catalogs Folder). If a file goes missing it is rebuilt. Your own
+`.cat` files (a newer CDMS release, say) can be converted with File → Convert
+CDMS Catalogs… or `linecat convert --catalogs DIR`.
+
+The catalog data come from the Cologne Database for Molecular Spectroscopy
+([CDMS](https://cdms.astro.uni-koeln.de/)); please cite Müller et al. 2001,
+A&A 370, L49; Müller et al. 2005, J. Mol. Struct. 742, 215; and Endres et al.
+2016, J. Mol. Spectrosc. 327, 95. The catalog format and the SPCAT program are
+described by Pickett et al. 1998, J. Quant. Spectrosc. Radiat. Transfer 60, 883.
+The CDMS documentation pages included with linecat are reproduced with credit
+to CDMS.
+
+## Documentation
+
+Help → User Guide opens the User Guide (PDF): the windows, the energy-level
+diagram, converting catalogs, the command line, adding a species, and the
+equations behind the derived columns. What changed in each version is in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+The window tests run offscreen with the small catalog in `tests/data/`.
+The User Guide sources are in `docs/` (`user_guide.tex`, with the equations in
+`equations.tex`); after a change, `sh tools/build_docs.sh` rebuilds it into
+`src/linecat/data/user_guide.pdf` (needs a TeX installation, e.g. MacTeX).
+The screenshots in `docs/figures/` are taken by hand on a Mac (⌘⇧4, Space,
+⌥-click for a window without shadow). Pushing a tag `vX.Y.Z` publishes a
+GitHub Release with that version's section of `CHANGELOG.md`.
+
+## Citing
+
+If you use linecat in published work, please cite it; GitHub's **Cite this
+repository** button gives the reference (from `CITATION.cff`). Please also
+cite CDMS for the catalog data (see [Catalogs](#catalogs)).
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+## Author
+
+Vahid Anari ·
+[GitHub](https://github.com/vahid-anari) ·
+[LinkedIn](https://www.linkedin.com/in/vahid-anari/)
+
+Related projects: [mbsolver](https://github.com/vahid-anari/mbsolver) ·
+[sciwidgets](https://github.com/vahid-anari/sciwidgets) ·
+[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio)

linecat-0.9.0/README.md

@@ -0,0 +1,132 @@
+# linecat
+
+[![tests](https://github.com/vahid-anari/linecat/actions/workflows/tests.yml/badge.svg)](https://github.com/vahid-anari/linecat/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/linecat)](https://pypi.org/project/linecat/)
+[![Python](https://img.shields.io/pypi/pyversions/linecat)](https://pypi.org/project/linecat/)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+**linecat** (Line Catalog Explorer) is a desktop viewer for spectral line catalogs
+such as [CDMS](https://cdms.astro.uni-koeln.de/). It loads a catalog converted
+to CSV, filters the transitions by frequency range and by the quantum numbers of
+the upper and lower states, shows the result in a table, exports the selection,
+and draws an interactive energy-level diagram of the selected transitions
+(with secondary transitions, hover information and a LaTeX/TikZ export).
+
+Supported species: OH, CH3OH, SiO, NH3. Adding a species means adding its
+quantum-number rules to `linecat/molecules.py`.
+
+<img src="https://raw.githubusercontent.com/vahid-anari/linecat/main/docs/figures/main_window.png" width="700" alt="linecat main window: quantum-number filters, frequency range and the table of OH lines">
+
+<img src="https://raw.githubusercontent.com/vahid-anari/linecat/main/docs/figures/diagram.png" width="700" alt="Energy-level diagram of the selected OH transitions with the transition table">
+
+## Installation
+
+Python 3.10 or newer. With [pipx](https://pipx.pypa.io/) (its own environment, recommended):
+
+```
+pipx install linecat
+```
+
+or with pip, in an environment of your choice:
+
+```
+pip install linecat
+```
+
+To start it with a double-click, run once:
+
+```
+linecat install-app
+```
+
+This adds Line Catalog Explorer to your Applications folder (macOS), the Start menu
+(Windows) or the applications menu (Linux), with its own icon. It starts the linecat
+of the Python you ran the command with, and keeps working after updates.
+
+To update, use Help → Check for Updates… in the app (it also checks quietly at
+start-up) or `linecat update` in a terminal.
+
+For development, install from a clone: `git clone https://github.com/vahid-anari/linecat.git`,
+then `pip install -e ".[dev]"` in the folder; such a copy is updated with `git pull`.
+
+## Use
+
+```
+linecat                       open the viewer
+linecat my_catalog.csv        open a catalog at start
+linecat convert               convert the shipped CDMS files into the current folder
+linecat convert OH --catalogs my_cats --output-dir out   convert your own .cat files
+linecat update                update from PyPI (asks first; --check only looks)
+linecat install-app           add the app to Applications / Start menu (--remove to undo)
+linecat --version
+```
+
+File → Open Built-in Catalog → OH / CH3OH / SiO / NH3 (⌘1–⌘4) opens a
+catalog that ships with linecat; File → Open Catalog… loads any other CSV; the quantum-number filters and the
+frequency range narrow the table; File → Export Table as CSV… writes what is
+shown; Transitions → Show Energy-Level Diagram draws the selected lines
+(hover for ν and τ, double-click a transition for the lines from its lower
+level). Right-click a column header for colours, alignment, font and columns.
+
+## Catalogs
+
+linecat ships, for OH, CH3OH, SiO and NH3, the CDMS `.cat` files, the CDMS
+documentation of each entry (PDF) and a picture of the molecule, one folder per
+species (`src/linecat/data/molecules/<SPECIES>/`); the main window shows them in
+its Molecule box, and Help → CDMS Documentation opens the general CDMS
+documents. On first start, and after every linecat update, it
+converts them to read-only CSV files in the application-data folder
+(macOS: `~/Library/Application Support/linecat/catalogs/`; File → Show
+Built-in Catalogs Folder). If a file goes missing it is rebuilt. Your own
+`.cat` files (a newer CDMS release, say) can be converted with File → Convert
+CDMS Catalogs… or `linecat convert --catalogs DIR`.
+
+The catalog data come from the Cologne Database for Molecular Spectroscopy
+([CDMS](https://cdms.astro.uni-koeln.de/)); please cite Müller et al. 2001,
+A&A 370, L49; Müller et al. 2005, J. Mol. Struct. 742, 215; and Endres et al.
+2016, J. Mol. Spectrosc. 327, 95. The catalog format and the SPCAT program are
+described by Pickett et al. 1998, J. Quant. Spectrosc. Radiat. Transfer 60, 883.
+The CDMS documentation pages included with linecat are reproduced with credit
+to CDMS.
+
+## Documentation
+
+Help → User Guide opens the User Guide (PDF): the windows, the energy-level
+diagram, converting catalogs, the command line, adding a species, and the
+equations behind the derived columns. What changed in each version is in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+## Development
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+The window tests run offscreen with the small catalog in `tests/data/`.
+The User Guide sources are in `docs/` (`user_guide.tex`, with the equations in
+`equations.tex`); after a change, `sh tools/build_docs.sh` rebuilds it into
+`src/linecat/data/user_guide.pdf` (needs a TeX installation, e.g. MacTeX).
+The screenshots in `docs/figures/` are taken by hand on a Mac (⌘⇧4, Space,
+⌥-click for a window without shadow). Pushing a tag `vX.Y.Z` publishes a
+GitHub Release with that version's section of `CHANGELOG.md`.
+
+## Citing
+
+If you use linecat in published work, please cite it; GitHub's **Cite this
+repository** button gives the reference (from `CITATION.cff`). Please also
+cite CDMS for the catalog data (see [Catalogs](#catalogs)).
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+## Author
+
+Vahid Anari ·
+[GitHub](https://github.com/vahid-anari) ·
+[LinkedIn](https://www.linkedin.com/in/vahid-anari/)
+
+Related projects: [mbsolver](https://github.com/vahid-anari/mbsolver) ·
+[sciwidgets](https://github.com/vahid-anari/sciwidgets) ·
+[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio)

linecat-0.9.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "linecat"
+version = "0.9.0"
+description = "Line Catalog Explorer: filter CDMS spectral line catalogs and draw energy-level diagrams"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Vahid Anari", email = "vahid.anari8@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["spectroscopy", "CDMS", "line catalog", "molecular lines", "energy-level diagram", "astronomy", "PySide6"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: MacOS X",
+    "Environment :: Win32 (MS Windows)",
+    "Environment :: X11 Applications :: Qt",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Astronomy",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "PySide6>=6.5",
+    "matplotlib>=3.7",
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "sciwidgets[table]~=0.10.4",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff", "build", "twine"]
+
+[project.scripts]
+linecat = "linecat.main:main"
+
+[project.urls]
+Homepage = "https://github.com/vahid-anari/linecat"
+Source = "https://github.com/vahid-anari/linecat"
+Issues = "https://github.com/vahid-anari/linecat/issues"
+Changelog = "https://github.com/vahid-anari/linecat/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+linecat = ["data/*.pdf", "data/molecules/*/*.cat", "data/molecules/*/*.pdf", "data/molecules/*/*.svg", "data/docs/*.pdf", "data/icons/*.png"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"

linecat-0.9.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

linecat-0.9.0/src/linecat/__init__.py

@@ -0,0 +1,8 @@
+"""linecat: viewer for spectral line catalogs."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("linecat")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

linecat-0.9.0/src/linecat/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m linecat``: the same as the ``linecat`` command (used by the app launcher)."""
+
+from linecat.main import main
+
+raise SystemExit(main())

linecat-0.9.0/src/linecat/app_info.py

@@ -0,0 +1,20 @@
+"""Names and addresses of the app, used by the window, the launcher and the update check."""
+
+from linecat import __version__
+
+APP_NAME = "Line Catalog Explorer"
+"""Name shown to the user (window, splash, launcher)."""
+
+APP_VERSION = __version__
+"""Installed version (``0.0.0`` when linecat is not installed as a package)."""
+
+DIST_NAME = "linecat"
+"""Name of the package on PyPI."""
+
+GITHUB_REPO = "vahid-anari/linecat"
+"""GitHub repository (``owner/name``); its Releases hold the release notes."""
+
+PYPI_URL = f"https://pypi.org/project/{DIST_NAME}/"
+PYPI_JSON_URL = f"https://pypi.org/pypi/{DIST_NAME}/json"
+RELEASES_URL = f"https://github.com/{GITHUB_REPO}/releases"
+RELEASES_API_URL = f"https://api.github.com/repos/{GITHUB_REPO}/releases?per_page=30"

linecat-0.9.0/src/linecat/builtin.py

@@ -0,0 +1,103 @@
+"""Built-in catalogs: the CDMS sources shipped with linecat, converted once into a per-user folder.
+
+The `.cat` files live in the package (`linecat/data/molecules/<SPECIES>/`, next to the species'
+CDMS documentation PDFs and its picture). Their CSVs are written
+read-only to the user's application-data folder (on macOS
+`~/Library/Application Support/linecat/catalogs/`), next to a stamp file holding the linecat
+version that built them. `ensure_builtin_catalogs` rebuilds them when a CSV is missing or the
+stamp differs, so a new converter version regenerates them by itself.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+from typing import Callable
+
+from linecat import __version__
+from linecat.cdms import ConversionResult, convert_molecule_catalog
+from linecat.molecules import REGISTRY
+
+DATA_DIR = Path(__file__).resolve().parent / "data"
+SOURCES_DIR = DATA_DIR / "molecules"  # one folder per species: .cat files, documentation PDFs, <SPECIES>.svg
+DOCS_DIR = DATA_DIR / "docs"  # general CDMS documentation
+ICONS_DIR = DATA_DIR / "icons"
+APP_ICON = ICONS_DIR / "app_icon.png"  # made by tools/make_icon.py
+APP_IMAGE = ICONS_DIR / "app_image.png"  # splash picture, made by tools/make_splash.py
+STAMP_NAME = ".linecat-version"
+
+
+def molecule_image(species: str) -> Path | None:
+    """The species' picture (`<SPECIES>.svg` in its folder), if there is one."""
+    path = SOURCES_DIR / species / f"{species}.svg"
+    return path if path.is_file() else None
+
+
+def molecule_docs(species: str) -> list[Path]:
+    """The CDMS documentation PDFs of the species' entries, sorted by name."""
+    folder = SOURCES_DIR / species
+    return sorted(folder.glob("*.pdf")) if folder.is_dir() else []
+
+
+def general_docs() -> list[Path]:
+    """The general CDMS documentation PDFs, sorted by name."""
+    return sorted(DOCS_DIR.glob("*.pdf")) if DOCS_DIR.is_dir() else []
+
+
+def user_guide() -> Path:
+    """The User Guide PDF (built by tools/build_docs.sh)."""
+    return DATA_DIR / "user_guide.pdf"
+
+
+def builtin_dir() -> Path:
+    """Folder that holds the built-in CSV catalogs (created on demand)."""
+    from PySide6.QtCore import QStandardPaths
+
+    base = QStandardPaths.writableLocation(QStandardPaths.GenericDataLocation)
+    return Path(base) / "linecat" / "catalogs"
+
+
+def builtin_csv(species: str, folder: Path | None = None) -> Path:
+    """Path of the built-in CSV of ``species``."""
+    return (folder or builtin_dir()) / f"CDMS_{REGISTRY[species].species}.csv"
+
+
+def builtin_is_current(folder: Path | None = None) -> bool:
+    """True when every species' CSV exists and was built by this linecat version."""
+    folder = folder or builtin_dir()
+    stamp = folder / STAMP_NAME
+    if not stamp.is_file() or stamp.read_text().strip() != __version__:
+        return False
+    return all(builtin_csv(code, folder).is_file() for code in REGISTRY)
+
+
+def _remove(path: Path) -> None:
+    if path.exists():
+        os.chmod(path, stat.S_IWUSR | stat.S_IRUSR)
+        path.unlink()
+
+
+def ensure_builtin_catalogs(
+    folder: Path | None = None,
+    progress: Callable[[str, int, int], None] | None = None,
+) -> list[ConversionResult]:
+    """Build the built-in CSVs if any is missing or out of date; return what was built (empty if nothing).
+
+    `progress` is called with (species, rows done, rows total), as for `cdms.convert_all`.
+    """
+    folder = folder or builtin_dir()
+    if builtin_is_current(folder):
+        return []
+    folder.mkdir(parents=True, exist_ok=True)
+    _remove(folder / STAMP_NAME)
+    results = []
+    for code in REGISTRY:
+        target = builtin_csv(code, folder)
+        _remove(target)
+        callback = (lambda done, total, code=code: progress(code, done, total)) if progress is not None else None
+        result = convert_molecule_catalog(code, outdir=folder, catalogs_dir=SOURCES_DIR, progress=callback)
+        os.chmod(result.path, stat.S_IRUSR | stat.S_IRGRP | stat.S_IROTH)  # read-only
+        results.append(result)
+    (folder / STAMP_NAME).write_text(__version__ + "\n")
+    return results