API Reference - NEUROVEDIK

🔧 C API

The C API provides low-level access to all NEUROVEDIK functionality. Include <neurovedik.h> to access these functions.

#include "neurovedik.h"

💾 Memory Management

Function	Description
`nv_alloc(size_t limbs)`	Allocate a BigInt with specified number of 64-bit limbs. Returns NULL on failure. Memory is 64-byte aligned for SIMD.
`nv_free(BigInt* n)`	Free a BigInt allocated by nv_alloc. Safe to call with NULL.
`nv_realloc(BigInt* n, size_t new_limbs)`	Resize a BigInt. Returns new pointer (may differ from input).
`nv_copy(BigInt* dst, const BigInt* src)`	Copy src to dst. dst must have sufficient capacity.
`nv_swap(BigInt* a, BigInt* b)`	Swap two BigInts in constant time. Swaps pointers, not content.

c Example

// Allocate 2048-bit integer (32 × 64-bit limbs)
BigInt* a = nv_alloc(32);
BigInt* b = nv_alloc(32);

// Use the integers...
nv_from_hex(a, "ABC123...");

// Cleanup
nv_free(a);
nv_free(b);

🧮 Arithmetic Operations

Function	Description
`nv_add(a, b, result)`	Add two BigInts: result = a + b
`nv_subtract(a, b, result)`	Subtract: result = a - b. Returns borrow.
`nv_multiply(a, b, result)`	Multiply using Smart Dispatcher. Auto-selects optimal algorithm.
`nv_multiply_vedic(a, b, result)`	Force Vedic Urdhva multiplication (AVX-512 accelerated).
`nv_multiply_karatsuba(a, b, result)`	Force Karatsuba divide-and-conquer multiplication.
`nv_divide(a, b, quotient, remainder)`	Division: quotient = a / b, remainder = a % b
`nv_shift_left(n, bits, result)`	Left shift by specified number of bits.
`nv_shift_right(n, bits, result)`	Right shift by specified number of bits.

🔐 Cryptographic Operations

Function	Description
`nv_modexp(base, exp, mod, result)`	Modular exponentiation: result = base^exp mod mod. Constant-time.
`nv_mod(a, m, result)`	Modular reduction: result = a mod m
`nv_mod_inverse(a, m, result)`	Modular inverse: result = a⁻¹ mod m. Returns 0 if no inverse.
`nv_gcd(a, b, result)`	Greatest common divisor using Binary GCD.
`nv_extended_gcd(a, b, g, x, y)`	Extended Euclidean: g = gcd(a,b), ax + by = g
`nv_is_prime(n, rounds)`	Miller-Rabin primality test with specified rounds.
`nv_montgomery_mul(a, b, n, n_inv, result)`	Montgomery multiplication for modular arithmetic chains.
`nv_crt_combine(r1, m1, r2, m2, result)`	Chinese Remainder Theorem: combine two congruences.

c RSA Decryption Example

// RSA decrypt with CRT optimization
BigInt *c, *d, *n, *p, *q, *dp, *dq, *qinv, *m;

// Compute m1 = c^dp mod p
nv_modexp(c, dp, p, m1);

// Compute m2 = c^dq mod q  
nv_modexp(c, dq, q, m2);

// Combine using CRT
nv_crt_combine(m1, p, m2, q, m);

// Result in m is 4x faster than direct c^d mod n

🐍 Python API

The Python module provides a Pythonic interface to all NEUROVEDIK functionality.

python

import NEUROVEDIK

# BigInt creation
a = NEUROVEDIK.BigInt.from_int(12345678901234567890)
b = NEUROVEDIK.BigInt.from_hex("DEADBEEF")
c = NEUROVEDIK.BigInt.from_bytes(b'\x01\x02\x03\x04')

# Arithmetic
result = NEUROVEDIK.multiply(a, b)
quotient, remainder = NEUROVEDIK.divide(a, b)

# Cryptographic
cipher = NEUROVEDIK.modexp(base, exp, mod)
is_prime = NEUROVEDIK.is_prime(n, rounds=40)
inverse = NEUROVEDIK.mod_inverse(a, m)

# Utilities
features = NEUROVEDIK.get_cpu_features()
print(f"AVX-512: {features['avx512f']}")

# Conversion
value = result.to_int()
hex_str = result.to_hex()
bytes_val = result.to_bytes()

Python Classes

Class/Method	Description
`BigInt.from_int(value)`	Create BigInt from Python int
`BigInt.from_hex(string)`	Create BigInt from hex string (with or without 0x prefix)
`BigInt.from_bytes(data)`	Create BigInt from bytes (big-endian)
`bigint.to_int()`	Convert to Python int
`bigint.to_hex()`	Convert to hex string
`bigint.bit_length()`	Return number of bits

Module Functions

Function	Description
`multiply(a, b)`	Returns a × b using optimal algorithm
`divide(a, b)`	Returns (quotient, remainder)
`modexp(base, exp, mod)`	Returns base^exp mod mod (constant-time)
`is_prime(n, rounds=40)`	Miller-Rabin test, returns bool
`gcd(a, b)`	Greatest common divisor
`mod_inverse(a, m)`	Returns a⁻¹ mod m, or None if no inverse
`get_cpu_features()`	Returns dict of CPU feature flags