Multi_field.h

Go to the documentation of this file.

/*    This file is part of the Gudhi Library - https://gudhi.inria.fr/ - which is released under MIT.
 *    See file LICENSE or go to https://gudhi.inria.fr/licensing/ for full license details.
 *    Author(s):       Hannah Schreiber, Clément Maria
 *
 *    Copyright (C) 2022 Inria
 *
 *    Modification(s):
 *      - YYYY/MM Author: Description of the modification
 */

 
#ifndef MATRIX_FIELD_MULTI_H_
#define MATRIX_FIELD_MULTI_H_
 
#include <utility>
#include <vector>
#include <gmpxx.h>
#include <stdexcept>
 
#include <gudhi/Debug_utils.h>
 
namespace Gudhi {
namespace persistence_fields {

template <unsigned int minimum, unsigned int maximum>
class Multi_field_element
{
 public:
  using Element = mpz_class;      
  using Characteristic = Element; 

  Multi_field_element() : element_(0)
  {
    static_assert(maximum >= 2, "Characteristics have to be positive.");
    static_assert(minimum <= maximum, "The given interval is not valid.");
    static_assert(minimum != maximum || _is_prime(minimum), "The given interval does not contain a prime number.");
 
    if (productOfAllCharacteristics_ == 1)
      throw std::runtime_error("The given interval does not contain a prime number.");
  }

  Multi_field_element(Element element) : element_(std::move(element))
  {
    static_assert(maximum >= 2, "Characteristics has to be positive.");
    static_assert(minimum <= maximum, "The given interval is not valid.");
    static_assert(minimum != maximum || _is_prime(minimum), "The given interval does not contain a prime number.");
 
    if (productOfAllCharacteristics_ == 1)
      throw std::runtime_error("The given interval does not contain a prime number.");
 
    mpz_mod(element_.get_mpz_t(), element_.get_mpz_t(), productOfAllCharacteristics_.get_mpz_t());
  }

  friend void operator+=(Multi_field_element& f1, Multi_field_element const& f2)
  {
    f1.element_ += f2.element_;
    mpz_mod(f1.element_.get_mpz_t(), f1.element_.get_mpz_t(), productOfAllCharacteristics_.get_mpz_t());
  }

  friend Multi_field_element operator+(Multi_field_element f1, Multi_field_element const& f2)
  {
    f1 += f2;
    return f1;
  }

  friend void operator+=(Multi_field_element& f, const Element& v)
  {
    f.element_ += v;
    mpz_mod(f.element_.get_mpz_t(), f.element_.get_mpz_t(), productOfAllCharacteristics_.get_mpz_t());
  }

  friend Multi_field_element operator+(Multi_field_element f, const Element& v)
  {
    f += v;
    return f;
  }

  friend Element operator+(Element v, Multi_field_element const& f)
  {
    v += f.element_;
    mpz_mod(v.get_mpz_t(), v.get_mpz_t(), productOfAllCharacteristics_.get_mpz_t());
    return v;
  }

  friend void operator-=(Multi_field_element& f1, Multi_field_element const& f2)
  {
    f1.element_ -= f2.element_;
    mpz_mod(f1.element_.get_mpz_t(), f1.element_.get_mpz_t(), productOfAllCharacteristics_.get_mpz_t());
  }

  friend Multi_field_element operator-(Multi_field_element f1, Multi_field_element const& f2)
  {
    f1 -= f2;
    return f1;
  }

  friend void operator-=(Multi_field_element& f, const Element& v)
  {
    f.element_ -= v;
    mpz_mod(f.element_.get_mpz_t(), f.element_.get_mpz_t(), productOfAllCharacteristics_.get_mpz_t());
  }

  friend Multi_field_element operator-(Multi_field_element f, const Element& v)
  {
    f -= v;
    return f;
  }

  friend Element operator-(Element v, Multi_field_element const& f)
  {
    // Element e(v);
    if (v >= productOfAllCharacteristics_)
      mpz_mod(v.get_mpz_t(), v.get_mpz_t(), productOfAllCharacteristics_.get_mpz_t());
    if (f.element_ > v) v += productOfAllCharacteristics_;
    v -= f.element_;
    return v;
  }

  friend void operator*=(Multi_field_element& f1, Multi_field_element const& f2)
  {
    f1.element_ *= f2.element_;
    mpz_mod(f1.element_.get_mpz_t(), f1.element_.get_mpz_t(), productOfAllCharacteristics_.get_mpz_t());
  }

  friend Multi_field_element operator*(Multi_field_element f1, Multi_field_element const& f2)
  {
    f1 *= f2;
    return f1;
  }

  friend void operator*=(Multi_field_element& f, const Element& v)
  {
    f.element_ *= v;
    mpz_mod(f.element_.get_mpz_t(), f.element_.get_mpz_t(), productOfAllCharacteristics_.get_mpz_t());
  }

  friend Multi_field_element operator*(Multi_field_element f, const Element& v)
  {
    f *= v;
    return f;
  }

  friend Element operator*(Element v, Multi_field_element const& f)
  {
    v *= f.element_;
    mpz_mod(v.get_mpz_t(), v.get_mpz_t(), productOfAllCharacteristics_.get_mpz_t());
    return v;
  }

  friend bool operator==(const Multi_field_element& f1, const Multi_field_element& f2)
  {
    return f1.element_ == f2.element_;
  }

  friend bool operator==(const Element& v, const Multi_field_element& f)
  {
    if (v < productOfAllCharacteristics_) return v == f.element_;
    Element e(v);
    mpz_mod(e.get_mpz_t(), e.get_mpz_t(), productOfAllCharacteristics_.get_mpz_t());
    return e == f.element_;
  }

  friend bool operator==(const Multi_field_element& f, const Element& v)
  {
    if (v < productOfAllCharacteristics_) return v == f.element_;
    Element e(v);
    mpz_mod(e.get_mpz_t(), e.get_mpz_t(), productOfAllCharacteristics_.get_mpz_t());
    return e == f.element_;
  }

  friend bool operator!=(const Multi_field_element& f1, const Multi_field_element& f2) { return !(f1 == f2); }

  friend bool operator!=(const Element& v, const Multi_field_element& f) { return !(v == f); }

  friend bool operator!=(const Multi_field_element& f, const Element& v) { return !(v == f); }
 
  // /**
  //  * @brief Assign operator.
  //  */
  // Multi_field_element& operator=(const Element& value)
  // {
  //   mpz_mod(element_.get_mpz_t(), value.get_mpz_t(), productOfAllCharacteristics_.get_mpz_t());
  //   return *this;
  // }

  friend void swap(Multi_field_element& f1, Multi_field_element& f2) noexcept { std::swap(f1.element_, f2.element_); }

  operator unsigned int() const { return element_.get_ui(); }

  explicit operator mpz_class() const { return element_; }

  [[nodiscard]] Multi_field_element get_inverse() const
  {
    return get_partial_inverse(productOfAllCharacteristics_).first;
  }

  [[nodiscard]] std::pair<Multi_field_element, Characteristic> get_partial_inverse(
      const Characteristic& productOfCharacteristics) const
  {
    GUDHI_CHECK(productOfCharacteristics >= 0 && productOfCharacteristics <= productOfAllCharacteristics_,
                std::invalid_argument(
                    "The given product is not the product of a subset of the current Multi-field characteristics."));
 
    Characteristic QR;
    mpz_gcd(QR.get_mpz_t(), element_.get_mpz_t(), productOfCharacteristics.get_mpz_t());  // QR <- gcd(x,QS)
 
    if (QR == productOfCharacteristics) return {Multi_field_element(), multiplicativeID_};  // partial inverse is 0
 
    Characteristic QT = productOfCharacteristics / QR;
 
    Characteristic inv_qt;
    mpz_invert(inv_qt.get_mpz_t(), element_.get_mpz_t(), QT.get_mpz_t());
 
    auto res = get_partial_multiplicative_identity(QT);
    res *= inv_qt;
 
    return {res, QT};
  }

  static Multi_field_element get_additive_identity() { return Multi_field_element<minimum, maximum>(); }

  static Multi_field_element get_multiplicative_identity()
  {
    return Multi_field_element<minimum, maximum>(multiplicativeID_);
  }

  static Multi_field_element get_partial_multiplicative_identity(const Characteristic& productOfCharacteristics)
  {
    GUDHI_CHECK(productOfCharacteristics >= 0 && productOfCharacteristics <= productOfAllCharacteristics_,
                std::invalid_argument(
                    "The given product is not the product of a subset of the current Multi-field characteristics."));
 
    if (productOfCharacteristics == 0 || productOfCharacteristics == productOfAllCharacteristics_) {
      return get_multiplicative_identity();
    }
    Multi_field_element<minimum, maximum> mult;
    for (unsigned int idx = 0; idx < primes_.size(); ++idx) {
      if ((productOfCharacteristics % primes_[idx]) == 0) {
        mult += partials_[idx];
      }
    }
    return mult;
  }

  static Characteristic get_characteristic() { return productOfAllCharacteristics_; }

  [[nodiscard]] Element get_value() const { return element_; }
 
 private:
  Element element_;
  static inline const std::vector<unsigned int> primes_ = []() {
    std::vector<unsigned int> res;
 
    unsigned int curr_prime = minimum;
    mpz_t tmp_prime;
    mpz_init_set_ui(tmp_prime, minimum);
    // test if min_prime is prime
    int is_prime = mpz_probab_prime_p(tmp_prime, 25);  // probabilistic primality test
 
    if (is_prime == 0) {  // min_prime is composite
      mpz_nextprime(tmp_prime, tmp_prime);
      curr_prime = mpz_get_ui(tmp_prime);
    }
 
    while (curr_prime <= maximum) {
      res.push_back(curr_prime);
      mpz_nextprime(tmp_prime, tmp_prime);
      curr_prime = mpz_get_ui(tmp_prime);
    }
    mpz_clear(tmp_prime);
 
    return res;
  }();
  static inline const Characteristic productOfAllCharacteristics_ = []() {
    Characteristic res = 1;
    for (const auto p : primes_) {
      res *= p;
    }
 
    return res;
  }();
  static inline const std::vector<Characteristic> partials_ = []() {
    std::vector<Characteristic> res;
 
    if (productOfAllCharacteristics_ == 1) return res;
 
    for (unsigned int p : primes_) {
      res.emplace_back(productOfAllCharacteristics_ / p);
      mpz_powm_ui(res.back().get_mpz_t(), res.back().get_mpz_t(), p - 1, productOfAllCharacteristics_.get_mpz_t());
    }
 
    return res;
  }();
  // If I understood the paper well, multiplicativeID_ always equals to 1. But in Clement's code,
  // multiplicativeID_ is computed (see commented lambda function below). TODO: verify with Clement.
  static inline const Element multiplicativeID_ = 1; /*[](){
           mpz_class res = 0;
           for (unsigned int i = 0; i < partials_.size(); ++i){
                   res = (res + partials_[i]) % productOfAllCharacteristics_;
           }
 
           return res;
   }();*/
 
  static constexpr bool _is_prime(const int p)
  {
    if (p <= 1) return false;
    if (p <= 3) return true;
    if (p % 2 == 0 || p % 3 == 0) return false;
 
    for (long i = 5; i * i <= p; i = i + 6)
      if (p % i == 0 || p % (i + 2) == 0) return false;
 
    return true;
  }
};
 
}  // namespace persistence_fields
}  // namespace Gudhi
 
#endif  // MATRIX_FIELD_MULTI_H_