holobit-sdk 1.0.9

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/usuario/holobit_sdk.git
cd holobit_sdk

# Instalar dependencias
pip install -r requirements_optional.txt
# Para tareas de desarrollo instala también las dependencias de 
# linting y cobertura
pip install -r requirements_dev.txt

🚀 Uso del SDK

🔹 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

from 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.

🌐 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:

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 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 🚀