holobit-sdk 1.1.1

SDK para arquitectura holográfica avanzada

Holobit SDK - Documentación Oficial

📌 Introducción

El Holobit SDK es un kit de desarrollo diseñado para la transpilación y ejecución de código holográfico cuántico. Su arquitectura multinivel permite trabajar con diferentes niveles de abstracción, optimizando el rendimiento en múltiples arquitecturas de hardware.

🔹 Características Principales

• Transpilador Cuántico Holográfico: Convierte código HoloLang en código máquina optimizado para arquitecturas x86, ARM y RISC-V.
• Backends C/C++, Rust y Go: Traducen programas HoloLang a código clásico en C, C++, Rust o Go, permitiendo un flujo tradicional de compilación.
• Optimización Avanzada: Reduce instrucciones redundantes y reutiliza registros para maximizar la eficiencia.
• Ejecución Multinivel: Soporte para bajo, medio y alto nivel en la programación holográfica.
• Compatibilidad con Múltiples Arquitecturas: x86, ARM y RISC-V.
• Integración con frameworks cuánticos: Qiskit, PennyLane, Cirq, AWS Braket y QuTiP.

📥 Instalación

Para instalar el SDK Holobit, sigue los siguientes pasos:

🔹 Requisitos Previos

• Python >=3.10 (versión mínima recomendada)
• pip actualizado
• Git (opcional, pero recomendado)

🔹 Instalación desde GitHub

# Clonar el repositorio
git clone https://github.com/Alphonsus411/holobit_SDK.git
cd holobit_SDK

# Instalar dependencias
pip install -r requirements_optional.txt
# Este archivo solo incluye herramientas de documentación, pruebas y utilidades
# generales; las bibliotecas destacadas en esta guía (pandas, scikit-learn,
# torch, FastAPI, gRPC y los SDKs de AWS/Azure/GCP) se instalan a través de los
# extras indicados más abajo.
# Para tareas de desarrollo instala también las dependencias de
# linting y cobertura
pip install -r requirements_dev.txt

# Para habilitar la API REST basada en FastAPI instala el extra dedicado
pip install .[api]
# Incluye FastAPI, bcrypt, uvicorn, grpcio, grpcio-tools y los SDK de AWS/Azure/GCP
# utilizados por los backends (`boto3`, `azure-identity`, `azure-mgmt-batch`,
# `google-cloud-compute`). Como alternativa, puedes instalarlo desde el archivo
# requirements_api.txt para entornos donde prefieras fijar el conjunto de
# dependencias:
# pip install -r requirements_api.txt
# Si ejecutas la API sin estos SDKs opcionales, los endpoints seguirán
# inicializando correctamente pero cualquier backend que los requiera devolverá
# un error 502 indicando la dependencia faltante.

# Para habilitar el puente de datos con pandas y frameworks de ML instala el extra `[ml]`
pip install .[ml]
# Incluye `pandas`, `scikit-learn` y `torch`, requeridas por
# `holobit_sdk.api.python_bridge` para cargar datasets, tensores y holobits
# desde DataFrames o arreglos NumPy.

Nota: aunque el repositorio en disco se llama holobit_SDK, el nombre del paquete instalable es holobit-sdk.

🔹 Instalación con o sin compilación

• Ruta compilada (recomendada cuando hay compilador disponible)

  pip install .[cython]
  

  Esto instalará Cython como dependencia extra, habilitará la compilación de los módulos .pyx y respetará el language_level=3. Para activar el perfilado de Cython (directivas profile=True y linetrace=True), exporta HOLOBIT_CYTHON_PROFILE=1 antes de instalar.

• Ruta en Python puro (sin compilador o sin Cython)

  HOLOBIT_DISABLE_CYTHON=1 pip install .[pure]
  

  El flujo ignora la compilación y carga automáticamente las variantes _py o las implementaciones .py equivalentes.

🔹 Extensiones Cython y ruta de instalación

El SDK incluye extensiones Cython para acelerar operaciones críticas. Durante la instalación con pip install .[cython] se compilan explícitamente los módulos holobit_sdk/assembler/virtual_machine.pyx y holobit_sdk/assembler/parser.pyx, además de los módulos de núcleo en holobit_sdk/core/*.pyx y los de holobit_sdk/quantum_holocron/**/*.pyx, con las optimizaciones language_level=3, boundscheck=False y cdivision=True. Si se habilita HOLOBIT_CYTHON_PROFILE=1, también se activan las directivas profile y linetrace para facilitar el análisis de rendimiento.

• Si hay un compilador disponible, la rueda resultante incluirá también las fuentes .pxd y los ficheros C generados (*.c) para facilitar la redistribución.
• Si el entorno no cuenta con compilador, el proceso de instalación continúa y el SDK utiliza automáticamente las implementaciones en Python puro sin modificar la API pública.
• Para forzar el modo sin compilación puedes definir HOLOBIT_DISABLE_CYTHON=1 pip install ., lo cual activa el fallback sin necesidad de eliminar dependencias de compilación.

La API se mantiene estable tanto en la versión compilada como en la de Python puro; la diferencia está únicamente en el rendimiento.

🔎 Verificación rápida de dependencias por método

• pip install -r requirements_optional.txt: instala utilidades para pruebas, documentación y soporte de publicación (pytest, matplotlib, rich, twine, qiskit, pennylane, entre otros). No incluye pandas, scikit-learn, torch, FastAPI ni los SDKs cloud.
• pip install -r requirements_dev.txt: añade herramientas de linting, cobertura y desarrollo local (por ejemplo, ruff, coverage, mypy).
• pip install .: instala el SDK base sin extras opcionales.
• pip install .[ml]: añade pandas, scikit-learn y torch para el puente de datos.
• pip install .[api] o pip install -r requirements_api.txt: instala la pila de servicios (FastAPI, uvicorn, grpcio, grpcio-tools, bcrypt) y los SDKs de AWS, Azure y GCP (boto3, azure-identity, azure-mgmt-batch, google-cloud-compute).
• Extras individuales .[aws], .[azure] o .[gcp]: instalan únicamente el SDK del proveedor correspondiente cuando no necesitas el resto de la pila de servicios.

🔹 Pruebas de consistencia y rendimiento con Cython

Se añaden pruebas parametrizadas para validar que las rutas de Cython y las de Python puro producen los mismos resultados numéricos en interactions y operations, incluso al forzar HOLOBIT_DISABLE_CYTHON.

• Consistencia de API en ambos modos:

  # Ejecuta las pruebas sin incluir los benchmarks opcionales
  pytest tests/test_interactions_operations_cython_toggle.py -m "not performance"
  

• Benchmarks opcionales (marcados como performance y slow):

  # Compara la versión compilada frente al fallback en Python
  pytest -m "performance" tests/test_interactions_operations_cython_toggle.py
  

• Casos adicionales para GeneticOptimizer y operations.entrelazar:

  # Verifica consistencia entre Cython y Python forzando HOLOBIT_DISABLE_CYTHON
  pytest tests/test_genetic_optimizer_operations_cython.py -m "not benchmark"
  
  # Ejecuta los microbenchmarks con pytest-benchmark (requiere tener instalado
  # el plugin `pytest-benchmark` y las extensiones Cython)
  pytest -m "benchmark and slow" tests/test_genetic_optimizer_operations_cython.py
  

  Estos benchmarks calculan el tiempo medio de GeneticOptimizer.run y de operations.entrelazar en modos compilado y Python puro. Las aserciones esperan que la versión Cython mantenga al menos un 10 % de mejora. Si el plugin de benchmarks o las extensiones compiladas no están disponibles, las pruebas se marcan como xfail para no bloquear la suite.

Los benchmarks usan pytest-benchmark y exigen que la versión compilada sea al menos un 10 % más rápida que la implementación en Python puro. En CI pueden habilitarse de forma opcional ejecutando los marcadores performance/slow.

📊 Resultados recientes (compilado vs. Python puro)

Modo	Comando	Resultado
Cython habilitado	pytest tests/test_interactions_operations_cython_toggle.py -m "not performance"	✅ 4 pruebas pasaron, 1 deseleccionada (1.06 s).
Cython habilitado	pytest tests/test_interactions_operations_cython_toggle.py -m performance	⚠️ 1 prueba marcada como skipped; el resto deseleccionadas (0.46 s).
Cython habilitado	pytest tests/test_interactions_operations_cython_toggle.py -m slow	⚠️ 1 prueba marcada como skipped; el resto deseleccionadas (0.45 s).
Python puro (HOLOBIT_DISABLE_CYTHON=1)	pytest tests/test_interactions_operations_cython_toggle.py -m "not performance"	✅ 4 pruebas pasaron, 1 deseleccionada (0.49 s).
Python puro (HOLOBIT_DISABLE_CYTHON=1)	pytest tests/test_interactions_operations_cython_toggle.py -m performance	⚠️ 1 prueba marcada como skipped; el resto deseleccionadas (0.51 s).
Python puro (HOLOBIT_DISABLE_CYTHON=1)	pytest tests/test_interactions_operations_cython_toggle.py -m slow	⚠️ 1 prueba marcada como skipped; el resto deseleccionadas (0.46 s).

Notas:

• Los skips en los marcadores performance/slow son esperados: los benchmarks están decorados para omitirse automáticamente cuando no se cumplen los requisitos opcionales de entorno.
• La suite de consistencia (not performance) es estable en ambos modos; la ruta en Python puro resulta ligeramente más rápida en este entorno controlado, aunque sin diferencias funcionales.

🔬 Perfilado de hotspots para priorizar Cython

Se incluye un script utilitario para identificar las rutas con mayor tiempo acumulado y generar un archivo intermedio para el proceso de build.

1. Ejecuta el perfilador desde la raíz del repositorio:

   python tools/profile_hotspots.py --limit 20 --min-time 0.002
   

   Variables de entorno útiles para activar o ajustar el perfilado sin tocar el código:

   • HOLOBIT_PROFILE_SEED: semilla para las cargas pseudoaleatorias.
   • HOLOBIT_PROFILE_TRANSPILE_ITERATIONS: repeticiones del bucle de transpilación.
   • HOLOBIT_PROFILE_ENTANGLE_SIZE: tamaño de los vectores de holobits en los experimentos de entrelazamiento.
   • HOLOBIT_PROFILE_POPULATION y HOLOBIT_PROFILE_GENERATIONS: parámetros del experimento genético fractal.
   • HOLOBIT_PROFILE_DATASET: ruta a un archivo de instrucciones sintéticas (texto plano) que sustituye al dataset embebido usado por el workload de transpilación; las líneas vacías y las que empiezan por # se ignoran y se barajan con la semilla indicada.
   • --limit, --min-time y --output controlan respectivamente la cantidad de entradas, el umbral de tiempo acumulado y la ruta de salida (predeterminada: build/cython_targets.json).

2. La consola mostrará el resumen de pstats ordenado por tiempo acumulado y la lista de rutas candidatas. Cada entrada se imprime como ruta:línea (función) -> tiempo_en_segundos para que puedas inspeccionar rápidamente qué módulos son los más costosos.

3. El archivo build/cython_targets.json incluye los mismos candidatos en formato estructurado (propiedades candidates y source_paths).

   • _load_cython_sources consume el campo source_paths para decidir qué módulos se intentarán compilar con Cython.
   • Para forzar la compilación de un módulo puedes añadir manualmente su ruta relativa (por ejemplo holobit_sdk/core/holobit.pyx o su par .py) en source_paths, incluso si no apareció en el perfilado.
   • Para excluir un módulo basta con eliminarlo de source_paths; si lo dejas vacío, el proceso de build volverá a explorar holobit_sdk/**/*.pyx de forma automática.

4. Si quieres ajustar las cargas simuladas, edita las funciones workload_transpiler, workload_entanglement o workload_fractal_genetics dentro de tools/profile_hotspots.py para que se parezcan más a tus casos de uso reales.

5. Para regenerar la lista de módulos a compilar con Cython hay un flujo simplificado basado en microbenchmarks:

   make profile-cython  # genera build/cython_targets.json con rutas críticas
   make wheel-profiled  # reutiliza el JSON anterior antes de construir la rueda
   

   • El script tools/profile_cython_targets.py ejecuta cargas cortas de evolución fractal y simulación de colisiones usando cProfile, ordena las funciones por tiempo acumulado y vuelca las rutas de origen en build/cython_targets.json bajo la clave source_paths.
   • _load_cython_sources (en setup.py) lee ese campo para decidir qué extensiones .pyx compilar; si el archivo no existe vuelve a explorar el árbol completo.
   • En CI puedes ejecutar make profile-cython antes del build y subir build/cython_targets.json como artefacto para mantener sincronizadas las rutas calientes entre ramas.

6. Si necesitas desactivar Cython temporalmente exporta la variable de entorno HOLOBIT_DISABLE_CYTHON=1 antes de invocar pip wheel . o python setup.py; el build ignorará cualquier ruta listada en source_paths y usará las implementaciones en Python puro.

🧩 Extras opcionales

Extra ml

El extra ml instala pandas, scikit-learn y torch, habilitando el puente de datos (holobit_sdk.api.python_bridge) para convertir DataFrames o arreglos NumPy en holobits y usarlos en flujos de PyTorch o scikit-learn. Instálalo con:

pip install .[ml]

Si importas funciones de holobit_sdk.api sin haber instalado estas dependencias, se mostrará el mismo mensaje que en tiempo de ejecución:

holobit_sdk.api.python_bridge requiere las dependencias del extra 'ml' (pandas, scikit-learn y torch). Instálalas con pip install .[ml] para habilitar las utilidades del puente de datos. Consulta la sección 'Extras opcionales' del README: https://github.com/Alphonsus411/holobit_SDK#extras-opcionales

Ejemplo breve de uso

Las utilidades del puente de datos se exponen directamente desde holobit_sdk.api, sin necesidad de importar módulos internos:

import pandas as pd
from holobit_sdk.api import HolobitDataset, holobit_dataloader, holobits_from_dataframe

df = pd.DataFrame(
    {
        "q1": [0.1, 0.2, 0.3],
        "q2": [0.4, 0.5, 0.6],
        "q3": [0.7, 0.8, 0.9],
        "q4": [1.0, 1.1, 1.2],
        "q5": [1.3, 1.4, 1.5],
        "q6": [1.6, 1.7, 1.8],
    }
)

# Convertir el DataFrame en holobits nativos del SDK
holobits = holobits_from_dataframe(df)

# Crear un Dataset compatible con PyTorch y un DataLoader para iterarlo
dataset = HolobitDataset(df)
loader = holobit_dataloader(df, batch_size=2, shuffle=False)
for batch in loader:
    print(batch)

🚀 Uso del SDK

🔹 Ejecución de módulos del paquete

Para evitar errores de importación relativa, los archivos dentro del paquete deben ejecutarse con python -m holobit_sdk.<ruta> (por ejemplo python -m holobit_sdk.quantum_holocron.fractal_evolution) o invocando ensure_package_context(globals()) al inicio del script. La alternativa recomendada es instalar el paquete y lanzar los módulos siempre con python -m en lugar de rutas relativas. Por ejemplo, el demostrador principal main.py puede ejecutarse correctamente tras instalar el SDK con:

python -m holobit_sdk.quantum_holocron.fractal_evolution --help
# o, si estás en el repositorio, añade ensure_package_context(globals()) y usa python main.py

🔹 Ejecución directa de módulos con python archivo.py

Si necesitas ejecutar un archivo dentro del paquete con python ruta/al/archivo.py (en lugar de usar python -m paquete.modulo), importa e invoca ensure_package_context al inicio para que los imports relativos funcionen como si el módulo se lanzara desde el paquete:

from holobit_sdk.utils.bootstrap import ensure_package_context

ensure_package_context(globals())

from holobit_sdk.core.holobit import Holobit
# resto del código...

Este bootstrap ajusta __package__ y __spec__ automáticamente, evitando fallos de importación relativa cuando el intérprete no conoce el contexto del paquete. Los entrypoints principales ya lo incluyen por defecto, como la CLI de HoloLang (holobit_sdk/multi_level/high_level/hololang_cli.py) y los servicios REST/gRPC (holobit_sdk/api/service.py y holobit_sdk/api/grpc_service.py), por lo que no necesitas añadirlo si llamas a esas herramientas.

🔹 Ejecución de ejemplos o módulos sueltos sin instalar el paquete

Al ejecutar archivos de examples/ o cualquier módulo individual del repositorio sin haber instalado holobit-sdk en el entorno, es necesario bootstrapear manualmente el contexto del paquete. De lo contrario, verás errores ImportError/ModuleNotFoundError al intentar resolver imports como from holobit_sdk... porque el intérprete no conoce la raíz del paquete.

Utiliza el helper ensure_package_context definido en holobit_sdk/utils/bootstrap.py o, en el caso de los ejemplos, importa el _bootstrap ya preparado en examples/_bootstrap.py. El patrón mínimo queda así:

from holobit_sdk.utils.bootstrap import ensure_package_context

# Corrige el contexto de paquete para que los imports relativos funcionen
ensure_package_context(globals())

from holobit_sdk.core.holobit import Holobit  # ya no dispara ImportError

En los scripts bajo examples/, basta con añadir import examples._bootstrap # noqa: F401 al inicio para lograr el mismo efecto. Ambas rutas delegan en holobit_sdk/utils/bootstrap.py, donde puedes consultar la implementación completa del helper si necesitas adaptarlo.

🔹 Transpilación de Código HoloLang

Para transpilar un archivo de código holográfico:

holobit-transpiler --input archivo.holo --arch x86

También puedes ejecutarlo con el módulo de Python:

python -m holobit_sdk.transpiler.machine_code_transpiler --input archivo.holo --arch x86

Esto generará un archivo con el código máquina optimizado para la arquitectura especificada.

🔹 Ejemplo de Uso en Código

Puedes importar la clase directamente desde el paquete completo holobit_sdk.transpiler.machine_code_transpiler:

from holobit_sdk.transpiler.machine_code_transpiler import MachineCodeTranspiler

transpiler = MachineCodeTranspiler("x86")
instruccion = "ADD H1 H2"
codigo_maquina = transpiler.transpile(instruccion)
print(codigo_maquina)  # ADD H1, H2 ; Registro reutilizado

Puedes encontrar más demostraciones en el directorio examples/.

🔹 Integración con Cirq, Braket y QuTiP

Los holobits pueden ejecutarse en diferentes frameworks cuánticos mediante adaptadores.

from holobit_sdk.quantum_integration import CirqAdapter, BraketAdapter, QutipAdapter

adapter = CirqAdapter()  # También BraketAdapter o QutipAdapter
circuito = adapter.holobit_to_native(holobit)
resultado = adapter.execute(circuito)

Cada adaptador convierte el Holobit a la representación nativa del backend y devuelve el estado resultante tras la ejecución.

Instalación de backends opcionales

Para habilitar cada adaptador instala el extra correspondiente:

• Cirq: pip install .[cirq] para ejecutar holobits en cirq mediante CirqAdapter.
• Braket: pip install .[braket] para usar BraketAdapter y simular en braket a través de LocalSimulator.
• QuTiP: pip install .[qutip] para generar y evolucionar estados qutip.Qobj con QutipAdapter.

Si sólo necesitas el SDK principal puedes instalarlo sin extras (pip install .), y añadir después el backend que desees.

🌐 Servicio Web de Compilación y Ejecución

El SDK incluye un servicio REST basado en FastAPI para compilar y ejecutar Holobits mediante los backends definidos en holobit_sdk.cloud.

Configuración

• HOLOBIT_PORT: puerto del servidor (por defecto 8000).
• HOLOBIT_BACKEND: backend a utilizar (aws, azure o gcp).
• HOLOBIT_USER y HOLOBIT_PASSWORD_HASH: usuario y hash bcrypt de la contraseña.

Proveedores de secretos

Los backends AWSBackend y AzureBackend pueden recibir un objeto que implemente la interfaz CredentialsProvider para obtener credenciales desde servicios externos como AWS Secrets Manager o Azure Key Vault.

from holobit_sdk.cloud import AWSBackend, CredentialsProvider

class SecretsManagerProvider(CredentialsProvider):
    def get_credentials(self) -> dict[str, str]:
        return {
            "AWS_ACCESS_KEY_ID": "...",
            "AWS_SECRET_ACCESS_KEY": "...",
        }

backend = AWSBackend(provider=SecretsManagerProvider())

Si el proveedor no responde o devuelve credenciales incompletas se registrará un error y se lanzará EnvironmentError.

Ejecución

export HOLOBIT_BACKEND=aws
export HOLOBIT_USER=usuario
export HOLOBIT_PASSWORD_HASH=$(python - <<'PY'
import bcrypt
print(bcrypt.hashpw(b'secreto', bcrypt.gensalt()).decode())
PY
)
python -m holobit_sdk.api.service

Los endpoints disponibles son:

• POST /compile con el campo code que devuelve job_id.
• POST /execute con job_id que devuelve el resultado. El identificador job_id acepta hasta 256 caracteres.

🔐 HTTPS opcional

Para cifrar la comunicación HTTP puedes generar un certificado y una clave privada. Por ejemplo, con OpenSSL:

openssl req -x509 -nodes -newkey rsa:4096 -keyout holobit.key -out holobit.crt -days 365 -subj '/CN=localhost'

Antes de iniciar el servicio exporta las rutas de ambos archivos:

export HOLOBIT_TLS_CERT=holobit.crt
export HOLOBIT_TLS_KEY=holobit.key
python -m holobit_sdk.api.service

Si los certificados no están definidos o faltan archivos, el servidor mostrará una advertencia y deberá desplegarse detrás de un proxy HTTPS.

Consulta examples/clients para ver ejemplos de clientes en JavaScript y Go.

🔌 Servicio gRPC

Además del servicio REST, el SDK ofrece un servicio gRPC definido en api/holobit.proto con los métodos Compile y Execute.

Para arrancarlo:

python -m holobit_sdk.api.grpc_service

El puerto se puede configurar con la variable HOLOBIT_PORT (por defecto 50051).

🔐 TLS opcional

Para cifrar la comunicación es necesario generar un certificado y una clave privada. Por ejemplo, con OpenSSL:

openssl req -x509 -nodes -newkey rsa:4096 -keyout holobit.key -out holobit.crt -days 365 -subj '/CN=localhost'

Antes de iniciar el servicio exporta las rutas de ambos archivos:

export HOLOBIT_TLS_CERT=holobit.crt
export HOLOBIT_TLS_KEY=holobit.key
python -m holobit_sdk.api.grpc_service

Si no se definen estas variables el servidor arrancará sin TLS, dejando la comunicación sin cifrar y expuesta a intercepciones; úsalo solo para desarrollo.

🔑 Autenticación por token

El servidor exige un token compartido para cada llamada gRPC. Genera un valor aleatorio y expórtalo antes de iniciar el servicio:

python - <<'PY'
import secrets; print(secrets.token_hex(32))
PY
export HOLOBIT_GRPC_TOKEN=el_valor_generado
python -m holobit_sdk.api.grpc_service

Los clientes autorizados deben incluir el token en la metadata con la clave x-holobit-token:

import os
with grpc.insecure_channel("localhost:50051") as channel:
    stub = holobit_pb2_grpc.HolobitServiceStub(channel)
    metadata = [("x-holobit-token", os.environ["HOLOBIT_GRPC_TOKEN"])]
    stub.Compile(holobit_pb2.CodeRequest(code="..."), metadata=metadata)

Las solicitudes sin token o con un valor incorrecto serán rechazadas con el estado UNAUTHENTICATED.

Los clientes en otros lenguajes pueden generarse compilando el archivo .proto correspondiente. Por ejemplo, para Python:

python -m grpc_tools.protoc -I api --python_out=. --grpc_python_out=. api/holobit.proto

En C++, Java, Go u otros lenguajes basta con ejecutar protoc con el plugin gRPC adecuado y apuntar al mismo archivo holobit.proto.

🔹 Flujo HoloLang → C/C++/Rust/Go → ensamblador

Además del código máquina directo, el compilador permite generar código C, C++, Rust o Go a partir de un programa HoloLang, manteniendo un flujo clásico de compilación:

from holobit_sdk.multi_level.high_level.compiler import HoloLangCompiler

compiler = HoloLangCompiler("rust")  # también "go", "c" o "cpp"
programa = "IMPRIMIR A"
codigo = compiler.compilar_y_ejecutar(programa)
print(codigo)

El resultado puede compilarse con gcc/clang, rustc o go build para producir ensamblador u objetos binarios.

🔹 Ejecución de HoloLang desde la línea de comandos

Puedes ejecutar código HoloLang directamente con el comando hololang:

hololang -c "CREAR H1 (0.1, 0.2, 0.3)" -c "IMPRIMIR H1"

O bien pasar un archivo con varias instrucciones y especificar el backend deseado:

hololang --file programa.holo --arch rust

Esto mostrará por pantalla el resultado de cada línea procesada.

🔹 Máquina Virtual del Ensamblador

El módulo assembler.virtual_machine permite ejecutar instrucciones holográficas en un entorno controlado.

from holobit_sdk.assembler.virtual_machine import AssemblerVM

vm = AssemblerVM()
programa = ["CREAR Q1 (0.1, 0.2, 0.3)", "CREAR Q2 (0.4, 0.5, 0.6)", "CREAR H1 {Q1, Q2}", "ROT H1 z 90"]
vm.run_program(programa)

Las instrucciones del ASIIC pueden escribirse con cualquier combinación de mayúsculas y minúsculas. Por ejemplo, rotar, Rotar y ROTAR se interpretan de la misma manera.

🧩 Macros y alias

El parser incluye un preprocesador que reconoce directivas #macro y #endmacro para definir plantillas reutilizables:

#macro CREAR_ROT nombre x y z
CREAR {nombre} ({x}, {y}, {z})
ROTAR {nombre} z 90
#endmacro

CREAR_ROT H1 0.1 0.2 0.3

Además, la máquina virtual carga alias al iniciar; por ejemplo ROTAR es un alias de ROT. También se incluyen alias como MEASURE → MEDIR, ENTRELAZAR → ENTANGLE y SUPERPOSICION → SUPERPOS. Las macros pueden eliminarse en tiempo de ejecución mediante assembler.macros.remove_macro("CREAR_ROT").

🔹 Instrucciones cuánticas esenciales

Las últimas versiones del lenguaje incluyen operaciones de nivel cuántico que pueden combinarse con macros y con la máquina virtual:

• SUPERPOS (alias: SUPERPOSICION): coloca un Holobit o qubit en superposición.

  CREAR Q1 (0.1, 0.2, 0.3)
  SUPERPOS Q1
  

• MEDIR (alias: MEASURE): colapsa el estado y almacena el resultado en parser.measurements.

  MEDIR Q1
  

• ENTANGLE (alias: ENTRELAZAR): entrelaza dos registros, propagando el colapso de uno sobre el otro.

  ENTANGLE Q1 Q2
  

• DECOHERENCIA: simula la pérdida de coherencia devolviendo un estado clásico aleatorio.

  DECOHERENCIA Q1
  

🔹 Manejo de grupos

Los Holobits pueden organizarse en grupos lógicos para operar sobre varios elementos simultáneamente:

CREAR H1 {Q1, Q2}
CREAR H2 {Q3, Q4}
GRUPO G1 {H1, H2}

🔹 Persistencia del estado del Holocron

Es posible guardar y restaurar el conjunto completo de holobits y grupos:

GUARDAR_ESTADO inicial
# ... realizar operaciones ...
RESTABLECER_ESTADO inicial

Estas instrucciones utilizan internamente Holocron.save_state y Holocron.restore_state para serializar y recuperar el contenido.

🔹 Estructuras de control

El ensamblador incorpora instrucciones de alto nivel para controlar el flujo:

• SI / SINO / FIN
• MIENTRAS / FIN
• PARA / FIN
• CASO / CUANDO / OTRO / FINCASO

MEDIR H1
SI H1
    ROT H1 z 90
SINO
    ROT H1 z 180
FIN

PARA 3
    ROT H1 x 30
FIN

CASO H1
    CUANDO 0
        ROT H1 y 45
    CUANDO 1
        ROT H1 y 90
    OTRO
        ROT H1 y 180
FINCASO

En HoloLang también pueden emplearse llaves para definir bloques con condicionales y estructuras de casos:

SI condicion {
    INSTRUCCION_A
} SINO {
    INSTRUCCION_B
}

CASO expresion {
    CUANDO 1 {
        ACCION_1
    }
    CUANDO 2 {
        ACCION_2
    }
    OTRO {
        ACCION_DEFECTO
    }
} FINCASO

🔹 Simulación de Holobits

El simulador HologramSimulator permite mover y rotar Holobits paso a paso, y visualizar cada estado en 3D.

from holobit_sdk.quantum_holocron.core.hologram_simulator import HologramSimulator
sim = HologramSimulator()
pasos = [{"traslacion": (0.1, 0, 0), "rotacion": ("z", 15)}]
sim.animate(holobit, pasos)

🔹 Interacciones básicas

El módulo holobit_sdk.core.interactions ofrece funciones sencillas para modificar el estado de los Holobits:

• confinar_quarks(holobit, limite): limita la posición de cada quark al rango [-limite, limite].
• cambiar_spin(holobit, nuevo_spin): ajusta el valor del spin del Holobit.
• sincronizar_spin(holobits): iguala el spin de un grupo de Holobits al promedio del conjunto.

from holobit_sdk.core import interactions

interactions.confinar_quarks(holobit, limite=0.5)
interactions.cambiar_spin(holobit, 1.0)

🔬 Arquitectura Interna del SDK

El SDK Holobit está estructurado en varios niveles:

1. Nivel Bajo: Manejo directo de registros y memoria holográfica.
2. Nivel Medio: Procesamiento cuántico holográfico.
3. Nivel Alto: Lenguaje de programación HoloLang y compilador asociado.

📖 Referencia Técnica

• Módulo transpiler: Contiene el transpilador de código holográfico a código máquina.
• Módulo execution: Maneja la ejecución de código transpilado en arquitecturas objetivo.
• Módulo debugger: Herramientas de depuración y análisis de código transpilado.

📄 Ejemplos de Código

Los ejemplos del SDK se encuentran en el directorio examples/ y pueden ejecutarse directamente con Python. Por ejemplo:

python examples/holobit_demo.py
python examples/hololang_compiler.py
python examples/hologram_simulation.py
python examples/new_instructions_demo.py

Cada script muestra una funcionalidad concreta del SDK. También puedes utilizar el transpilador de forma manual:

holobit-transpiler --input ejemplo.holo --arch x86

O bien con el módulo de Python:

python -m holobit_sdk.transpiler.machine_code_transpiler --input ejemplo.holo --arch x86

Expresiones ampliadas con SIQ

La instrucción SIQ permite evaluar los resultados de medición mediante expresiones complejas combinando operadores aritméticos y lógicos. Además de comparaciones simples entre un grupo y un valor, ahora es posible evaluar expresiones completas utilizando los resultados de medición disponibles:

SIQ (G1 + G2) > 1 {
    CREAR A (1)
} ELSEQ {
    CREAR B (1)
}

Los operadores admitidos incluyen ==, !=, <, >, <= y >=, así como operaciones aritméticas dentro de la expresión. Asimismo, SIQ soporta combinaciones lógicas mediante AND, OR y NOT, e incluso agrupar subexpresiones con paréntesis para un control detallado.

DESENTANGLE

La instrucción DESENTANGLE revierte el entrelazamiento entre dos Holobits, restaurando su independencia y evitando colapsos propagados. Es especialmente útil tras mediciones o manipulaciones intensivas.

ENTANGLE Q1 Q2
DESENTANGLE Q1 Q2

Operaciones adicionales con CANALIZAR

CANALIZAR abre un flujo de control sobre uno o varios Holobits donde se habilitan operaciones avanzadas como AMPLIFICAR, FILTRAR y REFRACTAR, las cuales no están disponibles fuera de este contexto.

CANALIZAR H1 {
    AMPLIFICAR H1 2;
    FILTRAR H1 z>0;
}

Sintaxis para secuencias de operaciones

Varias instrucciones pueden encadenarse en una sola línea utilizando el separador ;. Esto facilita describir secuencias de operaciones que el intérprete ejecutará de izquierda a derecha.

CREAR Q1 (0.1,0.2,0.3); ROTAR Q1 z 90; MEDIR Q1

Ejemplo combinado según el Holocron Cuántico

El siguiente fragmento muestra cómo integrar estas características para mantener la coherencia indicada por el Holocron Cuántico:

CREAR Q1 (0.1,0.2,0.3); CREAR Q2 (0.4,0.5,0.6)
ENTANGLE Q1 Q2
CANALIZAR {Q1,Q2} {
    AMPLIFICAR Q1 2;
    FILTRAR Q2 x>0;
}
SIQ (MEDIR Q1 + MEDIR Q2) >= 1 AND NOT(MEDIR Q1 == 0) {
    DESENTANGLE Q1 Q2;
    CREAR H1 {Q1, Q2};
} ELSEQ {
    ROTAR Q1 y 45;
}

🌿 Fractales Holográficos

Concepto, jerarquías de densidad y reglas morfométricas

Un fractal holográfico describe la distribución jerárquica de densidades dentro de un Holocron. Cada nivel genera subniveles con una densidad proporcional que sigue reglas morfométricas, permitiendo explorar la estructura cuántica con una escala autosimilar.

Uso desde Python

from holobit_sdk.quantum_holocron.core.holocron import Holocron
from holobit_sdk.quantum_holocron.fractal import Fractal
from holobit_sdk.core.holobit import Holobit
from holobit_sdk.core.quark import Quark
from holobit_sdk.visualization.fractal_plot import visualizar_fractal

def _crear_holocron():
    holo = Holocron()
    for i in range(10):
        q = [Quark(0, 0, 0) for _ in range(6)]
        aq = [Quark(0, 0, 0) for _ in range(6)]
        holo.add_holobit(f"hb{i}", Holobit(q, aq, spin=i))
    return holo

holo = _crear_holocron()
fractal = Fractal(holo)
fractal.hierarquia_superior = 20
fractal.generar()
fig, axes = visualizar_fractal(lambda **_: list(fractal.densidades.values()))

Uso desde Hololang

CREAR_FRACTAL F1 (densidad_max=20)
GRAFICAR_FRACTAL F1

Sintaxis de las nuevas instrucciones

El SDK incorpora instrucciones específicas para trabajar con fractales multidimensionales:

• CREAR_FRACTAL <id> (densidad_max=<N>, dimensiones=<D>): define un fractal con densidad máxima N y D dimensiones.
• SIMULAR_FRACTAL <id> pasos=<P>: ejecuta P iteraciones sobre el fractal existente.
• GRAFICAR_FRACTAL <id> modo=<modo>: muestra el fractal en modo 2D, 3D o animado.

Ejemplo completo:

CREAR_FRACTAL F1 (densidad_max=20, dimensiones=4)
SIMULAR_FRACTAL F1 pasos=10
GRAFICAR_FRACTAL F1 modo=animado

📝 Notas sobre archivos binarios

Los documentos de arquitectura se mantienen en PDF, pero debido a que los archivos binarios dificultan las revisiones, se evita editarlos directamente en el repositorio. Las actualizaciones deben registrarse en formatos de texto o imágenes vectoriales, generando los PDFs fuera del control de versiones.

📦 Despliegue y Distribución

El SDK Holobit será empaquetado y distribuido a través de GitHub Releases y PyPI.

🔹 Construcción del Paquete

python setup.py sdist bdist_wheel

🔹 Publicación en PyPI

pip install twine

# Subir el paquete
python -m twine upload dist/*

➕ Añadir nuevos backends cuánticos

Para integrar un nuevo backend cuántico en el SDK:

1. Crea una clase en holobit_sdk/quantum_integration que herede de QuantumAdapter.
2. Implementa el método holobit_to_native para traducir un Holobit al formato del backend.
3. Implementa execute para ejecutar la representación nativa y devolver su estado.
4. Añade pruebas correspondientes en holobit_sdk/quantum_integration/tests.

☁️ Backends en la Nube

El SDK incluye conectores simples para ejecutar trabajos Holobit en servicios de AWS, Azure y Google Cloud Platform.

Instalación de dependencias opcionales

Para cada proveedor instala el extra correspondiente:

# AWS
pip install .[aws]
# Azure
pip install .[azure]
# GCP
pip install .[gcp]

Variables de entorno requeridas

• AWS: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
• Azure: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID
• GCP: GOOGLE_APPLICATION_CREDENTIALS (ruta al archivo de credenciales)

Ejemplo de uso con AWS:

from holobit_sdk.cloud.aws import CloudBackend
backend = CloudBackend()
job_id = backend.submit_job({"payload": "..."})
backend.execute_job(job_id)

🧪 Pruebas

Para ejecutar las pruebas unitarias del proyecto debes instalar las dependencias opcionales. La suite completa requiere la librería qiskit, incluida en este archivo, para ejecutar las pruebas de integración cuántica:

pip install -r requirements_optional.txt

Si además deseas comprobar la cobertura de código instala las dependencias de desarrollo y ejecuta coverage:

pip install -r requirements_dev.txt

Luego ejecuta flake8 para verificar el estilo y coverage run junto con pytest:

flake8
coverage run -m pytest

Este repositorio cuenta con un flujo de Integración Continua en GitHub Actions que instala estas dependencias y ejecuta las pruebas en cada push y pull request.

♻️ Notas de migración

Para quienes actualicen desde versiones anteriores de Hololang:

• Las instrucciones SUPERPOS, MEDIR y ENTANGLE sustituyen a las antiguas SUP, MEASURE y ENTRELACE.
• La gestión de grupos se realiza con GRUPO en lugar de las primitivas heredadas SET.
• Las estructuras de control SI/SINO/FIN y MIENTRAS/FIN reemplazan a IF/ELSE/END.
• Las macros deben declararse mediante #macro y #endmacro; la sintaxis DEFINE ya no está soportada.

🛠 Mantenimiento y Contribución

Si deseas contribuir al SDK Holobit, puedes hacer un fork del repositorio y enviar un pull request con tus mejoras.

📧 Contacto y Soporte

Para cualquier consulta, reportes de errores o contribuciones, puedes contactarnos en [e-mail] o a través del repositorio en GitHub.

---

📌 Holobit SDK - Computación Cuántica Holográfica para el Futuro 🚀