install

Nota de documentação (fonte única): A documentação canônica está sendo consolidada em docs/. Comece por: memories/readme.md.

Instalação (Venv)

read -s -p "Digite seu GitHub Token: " GITHUB_TOKEN; echo; git clone https://$GITHUB_TOKEN@github.com/roytmanpiccoli/softqcos_core.git; unset GITHUB_TOKEN 2>/dev/null; echo "Clone concluído!"

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
# Apenas simulador/local
pip install -e ".[dev]"
# Com IBM Runtime habilitado
pip install -e ".[dev,ibm]"

cp .env.example .env   # ajuste valores, NÃO commitar segredos
set -a; source .env; set +a

# Suite funcional e artefatos (manifest/run.jsonl)
python scripts/run_tests.py --save

# Teste C (IBM Runtime: previsão vs hardware)
export USE_IBM=true
export IBM_TOKEN="seu-token-rotacionado"
export IBM_INSTANCE="org/projeto"   # opcional dependendo do canal
export IBM_CHANNEL="ibm_quantum_platform"
export IBM_SHOTS=1024
export SEED=12345

# Executa previsões (Aer+ruído) e coleta jobs IBM com tolerância estatística de 3pp
python scripts/run_tests.py --save

# O teste reprova se |p0_ibm - p0_pred| > 0.03 e o intervalo de Wilson de 95% não cobre p0_pred.
# Os registros incluem counts simulados vs hardware para evidence packs.

Execução de Experimento

python scripts/run_experiment.py

Docker (CPU)

docker compose -f docker/docker-compose.cpu.yml up --build
# Em outro terminal
docker exec -it softqcos-core-cpu bash

Docker (GPU)

Requer host com NVIDIA drivers + nvidia-container-toolkit.

docker compose -f docker/docker-compose.gpu.yml up --build
docker exec -it softqcos-core-gpu bash

Bootstrap Automático (opcional fora do repo)

Se estiver fora do diretório do projeto:

bash scripts/bootstrap_and_start.sh

Notas de Segurança

• Nunca commitar .env com IBM_TOKEN ou QCOS_API_TOKEN.
• Use .env.example como referência.
• Tokens devem ser rotacionados periodicamente (≥90 dias).

Limpeza

docker compose -f docker/docker-compose.cpu.yml down -v
docker compose -f docker/docker-compose.gpu.yml down -v