ParallelandDistributedComputation
===========================

Introduction
------------

The `ParallelandDistributedComputation` class in the `distancia` package is designed to facilitate the efficient computation of distances between data points using parallel processing techniques. This class allows users to leverage both multithreading and multiprocessing to speed up distance calculations, making it particularly useful in scenarios involving large datasets or computationally expensive distance metrics.

Core Idea
---------

The primary motivation behind the `ParallelDistanceCalculator` is to optimize distance computations in big data scenarios. By enabling parallel computation, the class reduces the overall computation time, making it feasible to handle large datasets and complex distance metrics. This class supports the use of custom distance functions, making it flexible enough to be applied in various research and practical contexts.

Utility
-------

The `ParallelandDistributedComputation` is especially valuable in tasks such as clustering, nearest neighbor search, and other machine learning or data analysis workflows where distance metrics are central. The ability to compute distances in parallel allows practitioners to scale their computations to large datasets without sacrificing performance. Users can choose between multithreading and multiprocessing, depending on the nature of their computation—whether it is I/O-bound or CPU-bound.

Example usage
-------------

.. code-block:: python

    from distancia import ParallelandDistributedComputation
    from distancia import Euclidean

    data_points = [[1, 2], [3, 4], [5, 6], [7, 8]]
    calculator = ParallelandDistributedComputation(data_points, Euclidean())

    # Compute distances from a reference point to all data points using multithreading
    reference_point = [0, 0]
    distances_to_ref_thread = calculator.compute_distances_parallel(reference_point, use_multiprocessing=False)
    print("Distances to reference point (threading):", distances_to_ref_thread)

    # Compute distances from a reference point to all data points using multiprocessing
    distances_to_ref_process = calculator.compute_distances_parallel(reference_point, use_multiprocessing=True)
    print("Distances to reference point (multiprocessing):", distances_to_ref_process)

    # Compute pairwise distances among all data points in parallel using multithreading
    pairwise_distances_thread = calculator.compute_distances_parallel(use_multiprocessing=False)
    print("Pairwise distances (threading):", pairwise_distances_thread)

.. code-block:: bash

    >>>Distances to reference point (threading): [2.23606797749979, 5.0, 7.810249675906654, 10.63014581273465]
    >>>Distances to reference point (multiprocessing): [2.23606797749979, 5.0, 7.810249675906654, 10.63014581273465]
    >>>Pairwise distances (threading): [2.8284271247461903, 5.656854249492381, 8.48528137423857, 2.8284271247461903, 5.656854249492381, 2.8284271247461903]

Academic Reference
------------------

Parallel and distributed computing has been a key area of research in computer science, particularly for large-scale data processing. The use of parallelism in distance computations aligns with concepts in parallel algorithms, which have been extensively studied in the academic community. For an in-depth discussion on parallel algorithms, refer to: :footcite:t:`parallelanddistributedcomputation`

.. footbibliography::



Conclusion
----------

The `ParallelandDistributedComputation` class significantly enhances the performance of the `distancia` package by introducing parallelism into distance calculations. By providing support for both multithreading and multiprocessing, it caters to a wide range of use cases, from small-scale I/O-bound tasks to large-scale CPU-bound computations. This flexibility ensures that users can efficiently compute distances, regardless of the complexity or size of their data, making `distancia` a robust tool in the field of data analysis and machine learning.