Working With Vectors - Infernet ML
Description: Infernet ML Documentation

Skip to content

# Vector Utilities in Ritual

Ritual provides powerful utilities for working with vectors and tensors in blockchain applications through the `RitualVector` class. This abstraction makes it easy to convert between different tensor formats and encode/decode vectors for on-chain use.

## Key Features

- Seamless conversion between NumPy arrays, PyTorch tensors, and on-chain representations
- Support for both IEEE754 and fixed-point arithmetic
- Wide range of supported data types (integers, floats, complex numbers)
- Efficient encoding and decoding for blockchain storage and computation

## Working with Different Tensor Formats

### Converting Between Formats

`RitualVector` makes it simple to convert between different tensor formats:

    import numpy as np
    import torch
    from ritual import RitualVector

    # Create from NumPy array
    numpy_array = np.array([1.0, 2.0, 3.0])
    vector = RitualVector.from_numpy(numpy_array)

    # Convert to PyTorch tensor
    torch_tensor = vector.tensor

    # Create from PyTorch tensor
    vector_from_torch = RitualVector.from_tensor(torch_tensor)

### Supported Data Types

Ritual supports a wide range of data types, automatically handling conversions between different formats:

- Floating point: float16, float32, float64, float128, float256
- Integers: int8, int16, int32, int64
- Unsigned integers: uint8, uint16, uint32, uint64
- Complex numbers: complex64, complex128
- Boolean values

## On-chain Representation

One of Ritual's key features is its ability to represent vectors on-chain using either IEEE754 or fixed-point arithmetic.

### Fixed-point Arithmetic

Fixed-point representation is commonly used in blockchain applications, similar to how ERC20 tokens handle decimals. This is particularly useful when working with smart contracts:

    # Create a vector
    vector = RitualVector.from_numpy(np.array([1.5, 2.7, 3.2]))

    # Encode using fixed-point arithmetic (18 decimals by default)
    encoded_fixed = vector.to_web3(arithmetic="fixed_point")

    # Decode back from fixed-point representation
    decoded_vector = RitualVector.from_web3(encoded_fixed)

### IEEE754 Arithmetic

For cases where IEEE754 floating-point precision is preferred:

    # Encode using IEEE754 arithmetic (default)
    encoded_ieee = vector.to_web3(arithmetic="ieee")

    # Decode from IEEE754 representation
    decoded_vector = RitualVector.from_web3(encoded_ieee)

## Working with Smart Contracts

When interfacing with smart contracts, `RitualVector` handles the encoding and decoding of vector data automatically:

    # Example of preparing vector data for a smart contract
    vector = RitualVector.from_numpy(model_weights)
    encoded_weights = vector.to_web3(
        arithmetic="fixed_point",
        fixed_point_scale=18  # Match your contract's decimal precision
    )

    # The encoded weights can now be sent to your smart contract
    contract.functions.updateWeights(encoded_weights).transact()

    # When reading from the contract, decode the data
    encoded_data = contract.functions.getWeights().call()
    decoded_vector = RitualVector.from_web3(encoded_data)
    weights = decoded_vector.numpy  # Convert back to NumPy array

## Best Practices

1. Choose the Right Arithmetic:
2. Use fixed-point arithmetic when working with smart contracts that expect decimal scaling

3. Use IEEE754 when precise floating-point representation is needed

4. Match Decimal Precision:

5. When using fixed-point arithmetic, make sure the `fixed_point_scale` matches your smart contract's decimal precision

6. Common values are 18 (default) or 6 decimals

7. Data Type Considerations:

8. Choose appropriate data types based on your precision needs and gas costs
9. Smaller data types (e.g., float16) use less gas but have lower precision

10. Larger data types (e.g., float256) provide more precision but cost more gas

11. Memory Efficiency:

12. Use the smallest data type that meets your precision requirements
13. Consider batching multiple vectors together when making contract calls to reduce gas costs