Struct RingValue

pub struct RingValue<R: RingBase> { /* private fields */ }

The most fundamental crate::ring::RingStore. It is basically a no-op container, i.e. stores a crate::ring::RingBase object by value, and allows accessing it.

Why is this necessary?

In fact, that we need this trait is just the result of a technical detail. We cannot implement

impl<R: RingBase> RingStore for R {}
impl<'a, R: RingStore> RingStore for &'a R {}

since this might cause conflicting implementations. Instead, we implement

impl<R: RingBase> RingStore for RingValue<R> {}
impl<'a, R: RingStore> RingStore for &'a R {}

This causes some inconvenience, as now we cannot chain crate::ring::RingStore in the case of crate::ring::RingValue. Furthermore, this trait will be necessary everywhere - to define a reference to a ring of type A, we now have to write &RingValue<A>.

To simplify this, we propose to use the following simple pattern: Create your ring type as

struct ABase { ... }
impl RingBase for ABase { ... } 

and then provide a type alias

type A = RingValue<ABase>;

Implementations

impl<R: RingBase> RingValue<R>

pub const fn from(value: R) -> Self

Wraps the given RingBase in a RingValue.

This is a dedicated function instead of an implementation of std::convert::From so that we can declare it const.

pub fn from_ref<'a>(value: &'a R) -> &'a Self

Creates a reference to a RingValue from a reference to the RingBase.

pub fn into(self) -> R

Unwraps the RingBase.

The more common case would be to get a reference, which can be done with RingStore::get_ring().

impl<T: PrimitiveInt> RingValue<StaticRingBase<T>>

pub const RING: StaticRing<T>

The singleton ring instance of StaticRing.

impl<A: Allocator + Clone> RingValue<RustBigintRingBase<A>>

pub fn new_with(allocator: A) -> RustBigintRing<A>

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl RingValue<RustBigintRingBase>

pub const RING: RustBigintRing

Default instance of RustBigintRing, the ring of arbitrary-precision integers.

impl<I: RingStore> RingValue<ZnBase<I>>

where I::Type: IntegerRing,

pub fn new(integer_ring: I, modulus: El<I>) -> Self

impl RingValue<ZnBase>

pub fn new(modulus: u64) -> Self

impl RingValue<ZnFastmulBase>

pub fn new(base: Zn) -> Option<Self>

impl<const N: u64, const IS_FIELD: bool> RingValue<ZnBase<N, IS_FIELD>>

pub const RING: Self

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<C: RingStore, J: RingStore> RingValue<ZnBase<C, J>>

where C::Type: ZnRing + CanHomFrom<J::Type>, J::Type: IntegerRing, <C::Type as ZnRing>::IntegerRingBase: IntegerRing + CanIsoFromTo<J::Type>,

pub fn new(summands: Vec<C>, large_integers: J) -> Self

Creates a new ring for Z/nZ with n = m1 ... mr where the mi are the moduli of the given component rings. Furthermore, the corresponding large integer ring must be provided, which has to be able to store values of size at least n^3.

impl<J: RingStore> RingValue<ZnBase<RingValue<ZnBase>, J>>

where ZnBase: CanHomFrom<J::Type>, J::Type: IntegerRing,

pub fn create_from_primes(primes: Vec<i64>, large_integers: J) -> Self

impl<C: RingStore, J: RingStore, A: Allocator + Clone> RingValue<ZnBase<C, J, A>>

where C::Type: ZnRing + CanHomFrom<J::Type>, J::Type: IntegerRing, <C::Type as ZnRing>::IntegerRingBase: IntegerRing + CanIsoFromTo<J::Type>,

pub fn new_with( summands: Vec<C>, large_integers: J, element_allocator: A, ) -> Self

Creates a new ring for Z/nZ with n = m1 ... mr where the mi are the moduli of the given component rings. Furthermore, the corresponding large integer ring must be provided, which has to be able to store values of size at least n^3.

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<C: RingStore, J: RingStore, A: Allocator + Clone> RingValue<ZnBase<C, J, A>>

where C::Type: ZnRing + CanHomFrom<J::Type>, J::Type: IntegerRing, <C::Type as ZnRing>::IntegerRingBase: IntegerRing + CanIsoFromTo<J::Type>,

pub fn from_congruence<I>(&self, el: I) -> ZnEl<C, A>

where I: IntoIterator<Item = El<C>>,

Given values ai for each component ring Z/miZ, computes the unique element in this ring Z/nZ that is congruent to ai modulo mi. The “opposite” function is Zn::get_congruence().

pub fn get_congruence<'a>( &self, el: &'a ZnEl<C, A>, ) -> impl 'a + VectorView<El<C>>

Given a in Z/nZ, returns the vector whose i-th entry is a mod mi, where the mi are the moduli of the component rings of this ring.

impl<R: RingStore> RingValue<DensePolyRingBase<R>>

pub fn new(base_ring: R, unknown_name: &'static str) -> Self

impl<R: RingStore, A: Allocator + Clone, C: ConvolutionAlgorithm<R::Type>> RingValue<DensePolyRingBase<R, A, C>>

pub fn new_with( base_ring: R, unknown_name: &'static str, element_allocator: A, convolution_algorithm: C, ) -> Self

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<R: RingStore> RingValue<SparsePolyRingBase<R>>

pub fn new(base_ring: R, unknown_name: &'static str) -> Self

impl RingValue<Complex64Base>

pub const RING: Self

pub const I: Complex64El

impl RingValue<Complex64Base>

pub fn abs(&self, val: Complex64El) -> f64

pub fn conjugate(&self, val: Complex64El) -> Complex64El

pub fn exp(&self, exp: Complex64El) -> Complex64El

pub fn closest_gaussian_int(&self, val: Complex64El) -> (i64, i64)

pub fn ln_main_branch(&self, val: Complex64El) -> Complex64El

pub fn is_absolute_approx_eq( &self, lhs: Complex64El, rhs: Complex64El, absolute_threshold: f64, ) -> bool

pub fn is_relative_approx_eq( &self, lhs: Complex64El, rhs: Complex64El, relative_limit: f64, ) -> bool

pub fn is_approx_eq( &self, lhs: Complex64El, rhs: Complex64El, precision: u64, ) -> bool

pub fn from_f64(&self, x: f64) -> Complex64El

pub fn root_of_unity(&self, i: i64, n: i64) -> Complex64El

pub fn re(&self, x: Complex64El) -> f64

pub fn im(&self, x: Complex64El) -> f64

impl RingValue<Real64Base>

pub const RING: RingValue<Real64Base>

impl<R, V> RingValue<FreeAlgebraImplBase<R, V>>

where R: RingStore, V: VectorView<El<R>>,

pub fn new(base_ring: R, rank: usize, x_pow_rank: V) -> Self

Creates a new FreeAlgebraImpl ring as extension of the given base ring.

The created ring is R[X]/(X^rank - sum_i x_pow_rank[i] X^i).

impl<R, V, A, C> RingValue<FreeAlgebraImplBase<R, V, A, C>>

where R: RingStore, V: VectorView<El<R>>, A: Allocator + Clone, C: ConvolutionAlgorithm<R::Type>,

pub fn new_with( base_ring: R, rank: usize, x_pow_rank: V, gen_name: &'static str, element_allocator: A, convolution: C, ) -> Self

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl RingValue<GaloisFieldBase<RingValue<AsFieldBase<RingValue<FreeAlgebraImplBase<RingValue<AsFieldBase<RingValue<ZnBase>>>, SparseMapVector<RingValue<AsFieldBase<RingValue<ZnBase>>>>>>>>>>

pub fn new(p: i64, degree: usize) -> Self

Creates a new instance of the finite/galois field GF(p^degree).

If you need more options for configuration, consider using GaloisField::new_with() or the most general GaloisField::create().

Example

let F25 = GaloisField::new(5, 2);
let generator = F25.canonical_gen();
let norm = F25.mul_ref_fst(&generator, F25.pow(F25.clone_el(&generator), 5));
let inclusion = F25.inclusion();
// the norm must be an element of the prime field
assert!(F25.base_ring().elements().any(|x| {
    F25.eq_el(&norm, &inclusion.map(x))
}));

impl<R, A, C> RingValue<GaloisFieldBase<RingValue<AsFieldBase<RingValue<FreeAlgebraImplBase<R, SparseMapVector<R>, A, C>>>>>>

where R: RingStore + Clone, R::Type: ZnRing + Field + SelfIso + CanHomFrom<StaticRingBase<i64>>, C: ConvolutionAlgorithm<R::Type>, A: Allocator + Clone,

pub fn new_with( base_field: R, degree: usize, allocator: A, convolution_algorithm: C, ) -> Self

Creates a new instance of a finite/galois field, as given-degree extension of the given base ring. The base ring must have prime characteristic.

If you need to specify the minimal polynomial used, see also GaloisField::create().

Example

Sometimes it is useful to have the base ring also be a field. This can e.g. be achieved by

#![feature(allocator_api)]
let F25 = GaloisField::new_with(Zn::new(5).as_field().ok().unwrap(), 2, Global, STANDARD_CONVOLUTION);
let generator = F25.canonical_gen();
let norm = F25.mul_ref_fst(&generator, F25.pow(F25.clone_el(&generator), 5));
let inclusion = F25.inclusion();
// the norm must be an element of the prime field
assert!(F25.base_ring().elements().any(|x| {
    F25.eq_el(&norm, &inclusion.map(x))
}));

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<Impl> RingValue<GaloisFieldBase<Impl>>

where Impl: RingStore, Impl::Type: Field + FreeAlgebra + FiniteRing, <<Impl::Type as RingExtension>::BaseRing as RingStore>::Type: ZnRing + Field,

pub fn create(base: Impl) -> Self

Most generic function to create a finite/galois field.

It allows specifying all associated data. Note also that the passed implementation must indeed be a field, and this is not checked at runtime. Passing a non-field is impossible, unless AsFieldBase::promise_is_field() is used.

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl RingValue<NumberFieldBase<RingValue<AsFieldBase<RingValue<FreeAlgebraImplBase<RingValue<RationalFieldBase<RingValue<MPZBase>>>, Vec<<<RingValue<RationalFieldBase<RingValue<MPZBase>>> as RingStore>::Type as RingBase>::Element>>>>>, RingValue<MPZBase>>>

pub fn try_new<P>(poly_ring: P, generating_poly: &El<P>) -> Option<Self>

where P: RingStore, P::Type: PolyRing, <P::Type as RingExtension>::BaseRing: RingStore<Type = BigIntRingBase>,

If the given polynomial is irreducible, returns the number field generated by it (with a root of the polynomial as canonical generator). Otherwise, None is returned.

If the given polynomial is not integral or not monic, consider using NumberField::try_adjoin_root() instead.

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn new<P>(poly_ring: P, generating_poly: &El<P>) -> Self

where P: RingStore, P::Type: PolyRing, <P::Type as RingExtension>::BaseRing: RingStore<Type = BigIntRingBase>,

Given a monic, integral and irreducible polynomial, returns the number field generated by it (with a root of the polynomial as canonical generator).

Panics if the polynomial is not irreducible.

If the given polynomial is not integral or not monic, consider using NumberField::adjoin_root() instead.

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn try_adjoin_root<P>( poly_ring: P, generating_poly: &El<P>, ) -> Option<(Self, El<Self>)>

where P: RingStore, P::Type: PolyRing, <P::Type as RingExtension>::BaseRing: RingStore<Type = RationalFieldBase<BigIntRing>>,

If the given polynopmial is irreducible, computes the number field generated by one of its roots, and returns it together with the root (which is not necessarily the canonical generator of the number field). Otherwise, None is returned.

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn adjoin_root<P>(poly_ring: P, generating_poly: &El<P>) -> (Self, El<Self>)

where P: RingStore, P::Type: PolyRing, <P::Type as RingExtension>::BaseRing: RingStore<Type = RationalFieldBase<BigIntRing>>,

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<Impl, I> RingValue<NumberFieldBase<Impl, I>>

where Impl: RingStore, Impl::Type: Field + FreeAlgebra, <Impl::Type as RingExtension>::BaseRing: RingStore<Type = RationalFieldBase<I>>, I: RingStore, I::Type: IntegerRing,

pub fn create(implementation: Impl) -> Self

Creates a new number field with the given underlying implementation.

Requires that all coefficients of the generating polynomial are integral.

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<R> RingValue<MultivariatePolyRingImplBase<R>>

where R: RingStore,

pub fn new(base_ring: R, variable_count: usize) -> Self

Creates a new instance of the ring base_ring[X0, ..., Xn] where n = variable_count - 1.

impl<R, A> RingValue<MultivariatePolyRingImplBase<R, A>>

where R: RingStore, A: Clone + Allocator + Send,

pub fn new_with( base_ring: R, variable_count: usize, max_supported_deg: u16, max_multiplication_table: (u16, u16), allocator: A, ) -> Self

Creates a new instance of the ring base_ring[X0, ..., Xn] where n = variable_count - 1.

The can represent all monomials up to the given degree, and will panic should an operation produce a monomial that exceeds this degree.

Furthermore, max_multiplication_table = (d1, d2) configures for which monomials a multiplication table is precomputed. In particular, a multiplication table is precomputed for all products where one summand has degree <= d2 and the other summand has degree <= d1. Note that d1 <= d2 is required.

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<I> RingValue<RationalFieldBase<I>>

where I: RingStore, I::Type: IntegerRing,

pub const fn new(integers: I) -> Self

pub fn num<'a>(&'a self, el: &'a El<Self>) -> &'a El<I>

See RationalFieldBase::num().

pub fn den<'a>(&'a self, el: &'a El<Self>) -> &'a El<I>

See RationalFieldBase::den().

impl RingValue<MPZBase>

pub const RING: MPZ

Available on crate feature mpir only.

impl<R> RingValue<AsLocalPIRBase<R>>

where R: RingStore, R::Type: ZnRing,

pub fn from_zn(ring: R) -> Option<Self>

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<R> RingValue<AsLocalPIRBase<R>>

where R: RingStore, R::Type: Field,

pub fn from_field(ring: R) -> Self

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<R> RingValue<AsLocalPIRBase<R>>

where R: RingStore, R::Type: PrincipalLocalRing,

pub fn from_localpir(ring: R) -> Self

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<R> RingValue<AsLocalPIRBase<R>>

where R: RingStore, R::Type: DivisibilityRing,

pub fn from_as_field(ring: AsField<R>) -> Self

Availability

This API is marked as unstable and is only available when the unstable-enable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Trait Implementations

impl<R: Clone + RingBase> Clone for RingValue<R>

fn clone(&self) -> RingValue<R>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<R: Debug + RingBase> Debug for RingValue<R>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<R: RingBase + Default> Default for RingValue<R>

fn default() -> Self

Returns the “default value” for a type.

impl<R: RingBase> RingStore for RingValue<R>

type Type = R

The type of the stored ring.

fn get_ring(&self) -> &R

Returns a reference to the stored ring.

fn clone_el(&self, val: &El<Self>) -> El<Self>

See RingBase::clone_el()

fn add_assign_ref(&self, lhs: &mut El<Self>, rhs: &El<Self>)

See RingBase::add_assign_ref()

fn add_assign(&self, lhs: &mut El<Self>, rhs: El<Self>)

See RingBase::add_assign()

fn sub_assign_ref(&self, lhs: &mut El<Self>, rhs: &El<Self>)

See RingBase::sub_assign_ref()

fn sub_self_assign(&self, lhs: &mut El<Self>, rhs: El<Self>)

See RingBase::sub_self_assign()

fn sub_self_assign_ref(&self, lhs: &mut El<Self>, rhs: &El<Self>)

See RingBase::sub_self_assign_ref()

fn negate_inplace(&self, lhs: &mut El<Self>)

See RingBase::negate_inplace()

fn mul_assign(&self, lhs: &mut El<Self>, rhs: El<Self>)

See RingBase::mul_assign()

fn mul_assign_ref(&self, lhs: &mut El<Self>, rhs: &El<Self>)

See RingBase::mul_assign_ref()

fn zero(&self) -> El<Self>

See RingBase::zero()

fn one(&self) -> El<Self>

See RingBase::one()

fn neg_one(&self) -> El<Self>

See RingBase::neg_one()

fn eq_el(&self, lhs: &El<Self>, rhs: &El<Self>) -> bool

See RingBase::eq_el()

fn is_zero(&self, value: &El<Self>) -> bool

See RingBase::is_zero()

fn is_one(&self, value: &El<Self>) -> bool

See RingBase::is_one()

fn is_neg_one(&self, value: &El<Self>) -> bool

See RingBase::is_neg_one()

fn is_commutative(&self) -> bool

See RingBase::is_commutative()

fn is_noetherian(&self) -> bool

See RingBase::is_noetherian()

fn negate(&self, value: El<Self>) -> El<Self>

See RingBase::negate()

fn sub_assign(&self, lhs: &mut El<Self>, rhs: El<Self>)

See RingBase::sub_assign()

fn add_ref(&self, lhs: &El<Self>, rhs: &El<Self>) -> El<Self>

See RingBase::add_ref()

fn add_ref_fst(&self, lhs: &El<Self>, rhs: El<Self>) -> El<Self>

See RingBase::add_ref_fst()

fn add_ref_snd(&self, lhs: El<Self>, rhs: &El<Self>) -> El<Self>

See RingBase::add_ref_snd()

fn add(&self, lhs: El<Self>, rhs: El<Self>) -> El<Self>

See RingBase::add()

fn sub_ref(&self, lhs: &El<Self>, rhs: &El<Self>) -> El<Self>

See RingBase::sub_ref()

fn sub_ref_fst(&self, lhs: &El<Self>, rhs: El<Self>) -> El<Self>

See RingBase::sub_ref_fst()

fn sub_ref_snd(&self, lhs: El<Self>, rhs: &El<Self>) -> El<Self>

See RingBase::sub_ref_snd()

fn sub(&self, lhs: El<Self>, rhs: El<Self>) -> El<Self>

See RingBase::sub()

fn mul_ref(&self, lhs: &El<Self>, rhs: &El<Self>) -> El<Self>

See RingBase::mul_ref()

fn mul_ref_fst(&self, lhs: &El<Self>, rhs: El<Self>) -> El<Self>

See RingBase::mul_ref_fst()

fn mul_ref_snd(&self, lhs: El<Self>, rhs: &El<Self>) -> El<Self>

See RingBase::mul_ref_snd()

fn mul(&self, lhs: El<Self>, rhs: El<Self>) -> El<Self>

See RingBase::mul()

fn square(&self, value: &mut El<Self>)

See RingBase::square()

fn coerce<S>(&self, from: &S, el: El<S>) -> El<Self>

where S: RingStore, Self::Type: CanHomFrom<S::Type>,

Tries to map the given element into this ring.

fn into_identity(self) -> Identity<Self>

Returns the identity map self -> self.

fn identity<'a>(&'a self) -> Identity<&'a Self>

Returns the identity map self -> self.

fn into_can_hom<S>(self, from: S) -> Result<CanHom<S, Self>, (S, Self)>

where Self: Sized, S: RingStore, Self::Type: CanHomFrom<S::Type>,

Returns the canonical homomorphism from -> self, if it exists, moving both rings into the CanHom object.

fn into_can_iso<S>(self, from: S) -> Result<CanIso<S, Self>, (S, Self)>

where Self: Sized, S: RingStore, Self::Type: CanIsoFromTo<S::Type>,

Returns the canonical isomorphism from -> self, if it exists, moving both rings into the CanHom object.

fn can_hom<'a, S>(&'a self, from: &'a S) -> Option<CanHom<&'a S, &'a Self>>

where S: RingStore, Self::Type: CanHomFrom<S::Type>,

Returns the canonical homomorphism from -> self, if it exists.

fn can_iso<'a, S>(&'a self, from: &'a S) -> Option<CanIso<&'a S, &'a Self>>

where S: RingStore, Self::Type: CanIsoFromTo<S::Type>,

Returns the canonical isomorphism from -> self, if it exists.

fn into_int_hom(self) -> IntHom<Self>

Returns the homomorphism Z -> self that exists for any ring.

fn int_hom<'a>(&'a self) -> IntHom<&'a Self>

Returns the homomorphism Z -> self that exists for any ring.

fn sum<I>(&self, els: I) -> El<Self>

where I: IntoIterator<Item = El<Self>>,

Computes the sum of all elements returned by the iterator.

fn try_sum<I, E>(&self, els: I) -> Result<El<Self>, E>

where I: IntoIterator<Item = Result<El<Self>, E>>,

Equivalent of RingStore::sum() if the producer of the ring elements can fail, in which case summation is aborted and the error returned.

fn prod<I>(&self, els: I) -> El<Self>

where I: IntoIterator<Item = El<Self>>,

Computes the product of all elements returned by the iterator.

fn pow(&self, x: El<Self>, power: usize) -> El<Self>

Raises the given element to the given power.

fn pow_gen<R: RingStore>( &self, x: El<Self>, power: &El<R>, integers: R, ) -> El<Self>

where R::Type: IntegerRing,

Raises the given element to the given power, which should be a positive integer belonging to an arbitrary IntegerRing.

fn format<'a>( &'a self, value: &'a El<Self>, ) -> RingElementDisplayWrapper<'a, Self>

Returns an object that represents the given ring element and implements std::fmt::Display, to use as formatting parameter.

fn println(&self, value: &El<Self>)

Prints the given element. Use for quick & dirty debugging.

fn characteristic<I: RingStore + Copy>(&self, ZZ: I) -> Option<El<I>>

where I::Type: IntegerRing,

See RingBase::characteristic().

impl<R: Copy + RingBase> Copy for RingValue<R>