cellify 0.1.2__tar.gz

cellify-0.1.2/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,46 @@
+name: Bug Report
+description: Report a reproducible bug in the application
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting a bug! Please fill out the form below to help us reproduce and fix the issue.
+  - type: input
+    id: title
+    attributes:
+      label: Bug Summary
+      placeholder: Short and descriptive summary of the bug
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      placeholder: |
+        1. Run `cellify -i POSCAR -d 2 2 2`
+        2. Observe the error
+      description: Please provide a minimal, reproducible example.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen instead?
+    validations:
+      required: false
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error Traceback or Logs (if applicable)
+      render: shell
+    validations:
+      required: false
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      placeholder: "e.g., macOS, Python 3.10"
+    validations:
+      required: false

cellify-0.1.2/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,36 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for your suggestion! Please complete the form below.
+  - type: input
+    id: summary
+    attributes:
+      label: Summary
+      placeholder: e.g., Add support for CP2K inputs
+    validations:
+      required: true
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: Why is this feature important? What problem does it solve?
+    validations:
+      required: false
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed Solution
+      description: Describe how you'd like the feature to work
+    validations:
+      required: false
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives
+      description: Any alternative solutions you've considered?
+    validations:
+      required: false

cellify-0.1.2/.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,22 @@
+name: Question
+description: Ask a question related to usage or development
+labels: [question]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        If you have a question, please provide sufficient context so we can assist you better.
+  - type: input
+    id: summary
+    attributes:
+      label: Question Summary
+      placeholder: e.g., How to generate a coherent interface between two lattices?
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Context or Background
+      description: What are you trying to do? Any relevant files or errors?
+    validations:
+      required: false

cellify-0.1.2/.github/workflows/autorelease.yml

@@ -0,0 +1,84 @@
+name: Auto Release on Version Bump
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  autorelease:
+    name: Check version and create release
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.check_tag.outputs.exists }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history and tags
+
+      - name: Get current version
+        id: get_version
+        run: |
+          VERSION=$(python -c "
+          with open('src/cellify/__init__.py') as f:
+              for line in f:
+                  if '__version__' in line:
+                      print(line.split('=')[1].strip().strip('\"\''))
+                      break
+          ")
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Check if tag exists
+        id: check_tag
+        run: |
+          TAG_NAME="v${{ env.VERSION }}"
+          if git rev-parse "$TAG_NAME" >/dev/null 2>&1; then
+            echo "Tag $TAG_NAME already exists. Skipping release."
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "Tag $TAG_NAME does not exist. A new release will be created."
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create GitHub Release
+        if: steps.check_tag.outputs.exists == 'false'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG_NAME="v${{ env.VERSION }}"
+          echo "Creating release for $TAG_NAME..."
+          gh release create "$TAG_NAME" \
+            --title "$TAG_NAME" \
+            --generate-notes
+
+  publish:
+    name: Build & Publish to PyPI
+    needs: autorelease
+    if: needs.autorelease.outputs.release_created == 'false'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cellify
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cellify-0.1.2/.github/workflows/check_cmdline.yml

@@ -0,0 +1,31 @@
+name: Test if cmdlines work
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+        working-directory: ${{ github.workspace }}
+
+      - name: cellify --help test
+        run: |
+          cellify --help

cellify-0.1.2/.github/workflows/pre-commit.yml

@@ -0,0 +1,30 @@
+name: pre-commit
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pre-commit
+          pre-commit install
+
+      - name: Run pre-commit
+        run: pre-commit run --all-files

cellify-0.1.2/.github/workflows/tests.yml

@@ -0,0 +1,37 @@
+name: Test Suite
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Run pytest
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[test]"
+
+      - name: Run tests
+        run: pytest
+
+      - name: Build package verification
+        run: |
+          pip install build
+          python -m build

cellify-0.1.2/.gitignore

@@ -0,0 +1,47 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Pytest / coverage
+.pytest_cache/
+.mypy_cache/
+.pylint_cache/
+
+# Virtual Environments
+.venv/
+venv/
+ENV/
+env/
+
+# Editor / System files
+.DS_Store
+.vscode/
+.idea/
+.flake8
+
+# AI Agent
+.agents/

cellify-0.1.2/.pre-commit-config.yaml

@@ -0,0 +1,53 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.2.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: check-json
+    -   id: check-added-large-files
+    -   id: check-toml
+- repo: https://github.com/pycqa/isort
+  rev: 6.0.1
+  hooks:
+    - id: isort
+      args: ["--profile", "black"]
+      files: ^src/
+- repo: https://github.com/psf/black
+  rev: 25.1.0
+  hooks:
+  - id: black
+    language_version: python3
+    files: ^src/
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: v1.15.0
+  hooks:
+    - id: mypy
+      args: [--ignore-missing-imports, --strict]
+      files: ^src/
+- repo: https://github.com/PyCQA/flake8
+  rev: "7.2.0"
+  hooks:
+  - id: flake8
+    # max-line-length setting is the same as black.
+    # E203 and W503 are ignored to prevent conflicts with black formatter.
+    # Complexity thresholds are set to a realistic value of 15 for practical CLI development.
+    args: [--max-line-length, "150", --ignore=E402,--ignore=E800,--ignore=E203,--ignore=W503,--max-complexity, "15", --max-expression-complexity=15, --max-cognitive-complexity=15]
+    additional_dependencies: [flake8-bugbear, flake8-builtins, flake8-eradicate, pep8-naming, flake8-expression-complexity, flake8-cognitive-complexity]
+    files: ^src/
+
+- repo: https://github.com/pylint-dev/pylint
+  rev: v3.3.7
+  hooks:
+    - id: pylint
+      name: pylint
+      entry: pylint
+      language: python
+      types: [python]
+      additional_dependencies: [ase, pymatgen, numpy]
+      # Disable overly strict pylint checks that are not pragmatic for CLI apps (e.g. too many locals/branches/statements/docstrings)
+      args: [--max-line-length,"150","--init-hook", "import sys; sys.path.insert(0, 'src')", "--disable=C0415,R0914,R0912,R0915,C0116,C0114"]
+      files: ^src/

cellify-0.1.2/GEMINI.md

@@ -0,0 +1,86 @@
+# GEMINI.md - Development History and Code Conventions
+
+This document records the development history, technical decisions, and code quality conventions of the `cellify` project, built collaboratively with the AI assistant "Gemini".
+
+---
+
+## 1. Project Background and Decisions
+
+### Purpose of Development
+To provide a command-line (CLI) tool that allows researchers to "easily" generate supercells and modify structures (doping, vacancies, surface slabs) for DFT calculations (VASP, Quantum ESPRESSO, etc.) while "completely preserving calculation parameters" in mixed format files.
+
+### Decision Process
+1.  **Survey of Existing Tools**: Analyzed the pros and cons of `cif2cell`, `phonopy`, `ASE`, and `pymatgen` (issues like brittle dependencies, manual header copy-pasting, etc.).
+2.  **Requirements Definition (README.md)**: Defined specifications including "Calculation-ready input files (especially QE `nat` auto-updates)" and "Automatic scaling based on minimum periodic distances".
+3.  **Naming Decision**: Chose **`cellify`** over other candidates like `scel` to support future general structure-modeling extensions.
+4.  **GitHub Connection**: Created and connected a public repository: `ToAmano/cellify`.
+5.  **Conventional Cell Conversion (Issue #5)**: Added `--conventional` flag to automatically convert primitive cells (commonly downloaded from materials databases) into conventional cells before performing other operations. This ensures intuitive defect index modeling and surface slab cutting.
+
+---
+
+## 2. Development & Coding Conventions
+
+### ① Complete Type Hinting 【Strictly Required】
+All Python modules under `src/cellify/` must have **complete type annotations** to ensure maintainability, static verification, and readability.
+
+*   **Function Signatures**: Specify parameter and return types using the `typing` module or built-in generics.
+    ```python
+    from typing import Tuple, Dict, Any
+    from pymatgen.core import Structure
+
+    def load_structure_file(filepath: str) -> Tuple[Structure, Dict[str, Any]]:
+        ...
+    ```
+*   **Local Variables**: Annotate local variables when they hold complex types.
+*   **Static Analysis**: Ensure all changes are validated and raise no errors when checked with static type checkers like `mypy`.
+
+### ② Parameter Preservation (Plain-Text Substitution)
+To prevent parse errors or accidental default overwrites (such as `K_POINTS None` introduction) in mixed-format calculations like Quantum ESPRESSO, adapters must keep calculation parameters (namelists, comments, formatting) in plain text and only modify parameters like `nat` and `ntyp` using regex matching. This is referred to as the `text_replace` engine.
+
+### ③ Modular Architecture (Separation of I/O Adapters and Core)
+To keep the codebase maintainable and open for future DFT software additions:
+*   **`adapters` Package**: Any format-specific file reading/writing (and parameter-preserving text substitutions) must be encapsulated under adapters inheriting the abstract `BaseAdapter` class (e.g., `EspressoAdapter`, `StandardAdapter`).
+*   **`core` Module**: Structural manipulation logic (supercells, defects, slabs) must be written as modular, pure-like functions that receive a `Structure` and return a modified `Structure` without being aware of input/output files.
+*   **Future Modulations**: The core logic remains in a single `core.py` for simplicity now, but is kept decoupled so it can be easily split into a `core/` package when the number of features increases.
+
+### ④ Branch Management and PR Lifecycle
+To maintain clean git history and keep features isolated:
+*   **One Branch Per Task/Feature**: Always create a new, dedicated branch for each feature or task. Do not implement unrelated requests or new tasks on an existing, open feature branch.
+*   **Cleanup After Merge**: Once a branch's Pull Request is merged into `main`, delete the branch locally and remotely to prevent reuse.
+
+---
+
+## 3. Testing & Linting Conventions and Execution
+To guarantee code quality and stability, unit/integration tests are managed using `pytest` inside the [tests/](file:///Users/amano/works/research/supercell/tests/) directory, and static analysis/formatting are managed by `pre-commit`.
+
+### ① Execution Before Commit 【Strictly Required】
+You **must** run and pass both the test suite and pre-commit checks locally before executing any `git commit`:
+
+1.  **Run Pytest**:
+    ```bash
+    # Install dependencies including test tools
+    pip install -e ".[test]"
+
+    # Run tests
+    pytest
+    ```
+2.  **Run Pre-commit**:
+    ```bash
+    # Install pre-commit hook (first time only to enable commit-time validation)
+    pre-commit install
+
+    # Run checks manually on all files before committing
+    pre-commit run --all-files
+    ```
+
+### ② Conventions
+*   Whenever implementing new features or fixing bugs, corresponding tests **must** be added to the `tests/` directory.
+*   Always maintain a fully passing (`passed`) state for all tests and linters in local verification and CI. Do not commit or push failing code.
+
+---
+
+## 4. Future Roadmap and Milestones
+*   Further stabilization and validation of vacancy generation (`--vacancy`) logic.
+*   Adding test data and verification for surface slab models (`--slab`).
+*   Integrating a lattice mismatch auto-relaxation module for heterostructures.
+*   Setting up linting and formatting configuration files (`mypy`, `flake8`, `black`, `ruff`).

cellify-0.1.2/NAMES.md

@@ -0,0 +1,27 @@
+# Name Candidates for the DFT Supercell Generator Tool
+
+A list of command-line name candidates representing the tool's identity (ease of use, parameter preservation, automatic expansion based on periodic distances, etc.), which are easy to type and memorable.
+
+---
+
+## Proposed Name Candidates
+
+| Name | Pronunciation | Command Example | Description & Origin |
+| :--- | :--- | :--- | :--- |
+| **`scel`** | s-cell | `scel -i POSCAR -o SPOSCAR -d 2 2 2` | Short for **S**uper**cel**l. Extremely short and optimal for CLI typing. Least prone to command conflicts. |
+| **`cellify`** | cell-i-fy | `cellify -i qe.in --min-dist 15.0` | **【Selected】** A verb meaning "to convert into a cell" or "to supercell". Sounds modern, friendly, and easy to remember. |
+| **`dftsc`** | d-f-t-s-c | `dftsc -i POSCAR -o SPOSCAR` | Short for **D**FT **S**uper**c**ell. Immediately conveys its DFT-specific usage and contains no fluff. |
+| **`readycell`** | ready-cell | `readycell -i qe.in -o qe_super.in` | Highlights the tool's core feature of creating **Calculation-ready** inputs (preserving calculations and updating headers automatically). |
+| **`scgen`** | s-c-gen | `scgen -i input.cif -d 2 2 2` | Short for **S**uper**c**ell **Gen**erator. An orthodox name that clearly defines its purpose. |
+| **`autosuper`** | auto-super | `autosuper -i POSCAR --min-dist 12.0` | Focuses on the smart feature of **automatically (Auto)** generating the optimal supercell based on a specified distance constraint. |
+
+---
+
+## Selection Criteria
+
+1.  **CLI Ergonomics**:
+    *   `scel` and `dftsc` are only 4–5 characters, making them highly efficient to type.
+    *   `cellify` and `scgen` are easy to type without spelling errors.
+2.  **PyPI Package Availability**:
+    *   Ensures that when publishing the tool to PyPI, it does not conflict with existing packages.
+    *   `cellify` is clear, clean, and stands out as a unique and descriptive project name.