Add Copilot instructions for repository context

.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