From b8b8e0943745b30a9678e28cd3722950ac099989 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 21 Jan 2026 21:18:16 +0000
Subject: [PATCH 1/2] Initial plan


From c2d73cf3a10d30962e4e8a7af5d5a5802e35ca44 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 21 Jan 2026 21:20:28 +0000
Subject: [PATCH 2/2] Add Copilot instructions file

Co-authored-by: fbischoff <7567292+fbischoff@users.noreply.github.com>
---
 .github/copilot-instructions.md | 150 ++++++++++++++++++++++++++++++++
 1 file changed, 150 insertions(+)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..eee807b
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,150 @@
+# Copilot Instructions for gradient-free-optimizer
+
+## Project Overview
+
+This is a Python project for gradient-free optimization with molecular geometry utilities. The main module `molecule.py` provides utilities for:
+- Reading XYZ files
+- Writing Turbomole `coord` files (with Angstrom to Bohr conversion)
+- Converting between XYZ and Z-matrix representations using Open Babel (`obabel`)
+- Inserting molecular coordinates into templates
+
+## Python Version Support
+
+- **Supported versions**: Python 3.9, 3.10, and 3.11
+- Always ensure code is compatible with all supported versions
+- CI runs tests against all three versions
+
+## Testing Framework
+
+### Test Structure
+- **Framework**: pytest
+- **Test location**: `tests/` directory
+- **Test files**: Use `test_*.py` naming convention
+- **Test fixtures**: Defined in `tests/conftest.py`
+
+### Running Tests
+```bash
+# Full test suite
+pytest -q
+
+# Single test file
+pytest tests/test_molecule.py -q
+
+# Specific test
+pytest tests/test_molecule.py::test_write_coord_from_xyz -q
+```
+
+### Test Conventions
+- Use `pytest.approx()` for floating-point comparisons
+- Use `tmp_path` fixture for temporary file operations
+- Mock `subprocess.run` when testing behavior without external dependencies (e.g., `obabel`)
+- Tests should not require Open Babel to be installed; mock subprocess calls when needed
+
+## Code Style and Conventions
+
+### General Guidelines
+- Follow PEP 8 style guidelines
+- Use type hints where appropriate (as seen in `molecule.py`)
+- Include docstrings for classes and public methods
+- Use descriptive variable names
+
+### Constants
+- Define constants at module level in UPPER_CASE (e.g., `ANGSTROM_TO_BOHR`)
+
+### Error Handling
+- Define custom exceptions for specific error cases (e.g., `ObabelNotFoundError`, `ObabelError`)
+- Provide informative error messages
+
+### Documentation
+- Module-level docstrings should describe the module's purpose and main functionality
+- Class docstrings should include:
+  - Description of the class purpose
+  - Important attributes
+  - Usage notes
+- Use triple-quoted strings with proper formatting
+
+## Dependencies
+
+### Runtime Dependencies
+- Python standard library (primary)
+- `numpy` (used in some computations)
+- External tool: `obabel` (optional, for format conversions)
+
+### Development Dependencies
+- `pytest` for testing
+- No additional linting tools currently configured
+
+### Virtual Environment
+Recommended setup:
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install pytest numpy
+```
+
+## Project Structure
+
+```
+.
+├── .github/
+│   └── workflows/          # CI/CD workflows
+├── tests/                  # Test files
+│   ├── conftest.py        # Pytest fixtures
+│   ├── test_molecule.py   # Molecule class tests
+│   └── test_kabsch.py     # Kabsch algorithm tests
+├── molecule.py            # Main molecule utilities module
+├── main.py               # Sample script/entry point
+└── README.md             # Project documentation
+```
+
+## CI/CD
+
+### GitHub Actions
+- **Workflow file**: `.github/workflows/python-pytest.yml`
+- **Trigger**: Pushes and PRs to `main` or `master` branches
+- **Matrix testing**: Runs on Python 3.9, 3.10, and 3.11
+- **Steps**:
+  1. Checkout code
+  2. Set up Python
+  3. Cache pip dependencies
+  4. Install dependencies (pytest and numpy)
+  5. Run pytest with `-q -r a` flags
+
+### CI Requirements
+- All tests must pass on all supported Python versions
+- No external dependencies (like Open Babel) required in CI
+
+## Special Considerations
+
+### Unit Conversions
+- Coordinates are stored in Angstrom internally
+- Turbomole output uses Bohr: `1 Angstrom = 1.889725988579 Bohr`
+- Use `ANGSTROM_TO_BOHR` constant for conversions
+
+### External Tool Integration
+- `obabel` is called via `subprocess` for format conversions
+- Code should gracefully handle missing `obabel` installation
+- Raise `ObabelNotFoundError` when `obabel` is not available
+- Tests should mock subprocess calls to avoid dependency on `obabel`
+
+### Z-matrix Support
+- Z-matrix functionality includes both parsing and generation
+- Coordinate representations (XYZ and Z-matrix) must be kept consistent
+- Pure Python implementation available as fallback
+
+## When Making Changes
+
+1. **Preserve backward compatibility** unless explicitly breaking changes are intended
+2. **Add tests** for new functionality following existing patterns
+3. **Update docstrings** when modifying public APIs
+4. **Ensure CI passes** on all Python versions
+5. **Keep dependencies minimal** - prefer standard library when possible
+6. **Handle edge cases** especially around file I/O and external process calls
+
+## File Operations
+
+- Use `pathlib.Path` for modern path handling
+- Use context managers (`with` statements) for file operations
+- Clean up temporary files appropriately
+- Support both string paths and Path objects where reasonable