Add documentation, testing infrastructure, and CI pipeline

[Copilot]

This repository implements FMQA (Factorization Machines with Quantum Annealing) using PyTorch, adapted from the original MXNet-based tsudalab/fmqa. It lacked documentation, testing, and automated verification.

Changes

• Documentation: Comprehensive README covering installation, usage patterns, and project structure. Includes citation for the original paper (Kitai et al., Phys. Rev. Research 2020).

• Licensing: MIT license at repository root with proper attribution to both SECQUOIA and the original Tsuda Laboratory implementation.

• Test Suite: 30 tests covering binary encoding utilities, grid-based optimization helpers, and FMQA integration with PyTorch and dimod samplers. Tests verify:

  • Bit encoding/decoding for coordinate representation
  • CSV grid loading with NaN handling
  • FMBQM training and sampling with simulated annealing
  • Variable type detection (BINARY/SPIN)

• CI Pipeline: GitHub Actions workflow running tests across Python 3.8-3.11 with coverage reporting to Codecov. Includes dependency caching and secure permissions configuration.

• Project Structure: Added __init__.py for proper package imports, .gitignore for build artifacts, and requirements-test.txt for reproducible test environments.

Example Usage

import numpy as np
from fmqa import FMBQM
import dimod

# Train surrogate model from observations
x_data = np.array([[0, 1, 0, 1], [1, 0, 1, 0]])
y_data = np.array([0.5, -0.3])
model = FMBQM.from_data(x_data, y_data, num_epoch=1000, learning_rate=1e-2)

# Optimize with annealing
sampler = dimod.SimulatedAnnealingSampler()
results = sampler.sample(model, num_reads=100)

All 30 tests pass with 73% coverage. CodeQL security analysis passes with no alerts.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add documentation, testing, and CI to this repository</issue_title>
<issue_description>This repository has an implementation of the codes here https://github.com/tsudalab/fmqa, but relying on PyTorch. We need to complete the documentation with a comprehensive README, acknowledge the original source of the code, add an MIT license, generate tests that verify code stability, and finally run them through CI on GitHub.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add documentation, testing, and CI to this repository #2

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.