*Space2Vec-sphereC+*
++++++++++++++++++++++++++++++++++++++++

:class:`SphereGridSpatialRelationLocationEncoder`
=================================================

Overview
--------

The :class:`SphereGridSpatialRelationLocationEncoder` is engineered for encoding spatial relationships between locations. It leverages the :class:`SphereGridSpatialRelationPositionEncoder` to initially encode spatial differences, then processes these through a customizable multi-layer feed-forward neural network to produce high-dimensional spatial embeddings.

Features
--------

- **Position Encoding**: Uses the :class:`SphereGridSpatialRelationPositionEncoder` for encoding spatial differences using sinusoidal functions.
- **Feed-Forward Neural Network**: Converts the position-encoded data into spatial embeddings through multiple neural network layers.

Configuration Parameters
------------------------

- `spa_embed_dim`: The dimensionality of the spatial embedding output.
- `coord_dim`: The dimensionality of the coordinate space (e.g., 2D, 3D).
- `device`: Computation device (e.g., 'cuda').
- `frequency_num`: Number of frequency components used in positional encoding.
- `max_radius`: Maximum spatial context radius.
- `min_radius`: Minimum spatial context radius.
- `freq_init`: Initialization method for frequency calculation, set to 'geometric'.
- `ffn_act`: Activation function for the feed-forward layers.
- `ffn_num_hidden_layers`: Number of hidden layers in the feed-forward network.
- `ffn_dropout_rate`: Dropout rate used in the feed-forward network.
- `ffn_hidden_dim`: Dimension of each hidden layer in the feed-forward network.
- `ffn_use_layernormalize`: Flag to enable layer normalization in the network.
- `ffn_skip_connection`: Flag to enable skip connections in the network.
- `ffn_context_str`: Context string for debugging and detailed logging.

Methods
--------

.. method:: forward(coords)
    :no-index:

- **Purpose**: Processes input coordinates through the encoder to produce final spatial embeddings.
- **Parameters**:
    - ``coords`` (List or np.ndarray): Coordinates to be processed, expected in the format `(batch_size, num_context_pt, coord_dim)`.
- **Returns**:
    - ``sprenc`` (Tensor): Spatial relation embeddings, shaped `(batch_size, num_context_pt, spa_embed_dim)`.

:class:`SphereGridSpatialRelationPositionEncoder`
=================================================

Features
--------

- **Sinusoidal Encoding**: Applies sinusoidal functions to encode spatial differences, enhancing the model's ability to learn from these features.
- **Configurable Parameters**: Supports customization of encoding parameters such as space dimensionality and computation device. 

.. image:: ../images/sphereC+.png
    :width: 100%
    :align: center
    :alt: sphereC-plus-transformation

Configuration Parameters
------------------------

- ``coord_dim``: Dimensionality of the space being encoded (e.g., 2D, 3D).
- ``frequency_num``: Number of frequencies used in sinusoidal encoding.
- ``device``: Specifies the computational device.

Methods
--------

.. method:: make_output_embeds(coords)
    :no-index:

- **Description**: Converts a batch of coordinates into spatial relation embeddings.
- **Parameters**:
    - ``coords``: Spatial differences to be encoded.
- **Returns**:
    - Spatial relation embeddings in high-dimensional space.

.. method:: forward(coords)
    :no-index:

- **Description**: Feeds processed coordinates through the encoder to generate final spatial embeddings.
- **Parameters**:
    - ``coords``: Coordinates to process.
- **Returns**:
    - Tensor of spatial relation embeddings.

Usage Example
=============

.. code-block:: python

    encoder = SphereGridSpatialRelationLocationEncoder(
        spa_embed_dim=64,
        coord_dim=2,
        device="cuda",
        frequency_num=16,
        max_radius=10000,
        min_radius=10,
        freq_init="geometric",
        ffn_act="relu",
        ffn_num_hidden_layers=1,
        ffn_dropout_rate=0.5,
        ffn_hidden_dim=256,
        ffn_use_layernormalize=True,
        ffn_skip_connection=True,
        ffn_context_str="SphereGridSpatialRelationEncoder"
    )

    coords = np.array([[34.0522, -118.2437], [40.7128, -74.0060]])  # Example coordinate data
    embeddings = encoder.forward(coords)

