Struct QDF

pub struct QDF<S>
where
    S: State,
{ /* private fields */ }

Object that represents quantized density fields.

Concept

QDF does not exists in any space - it IS the space, it defines it, it describes it so there are no space coordinates and it is your responsibility to deliver it. In future releases this crate will have module for projecting QDF into Euclidean space and will have a satelite crate to easlyy traverse and visualize space.

To sample specified region you have to know some space ID and gather the rest of information based on it neighbors spaces. It gives the ability to cotrol space density at specified locations, which can be used for example to simulate space curvature based on gravity.

Implementations

impl<S> QDF<S>

where S: State,

pub fn new(dimensions: usize, state: S) -> (Self, ID)

Creates new QDF information universe.

Arguments

• dimensions - Number of dimensions space contains.
• state - State of space.

Returns

Tuple of new QDF object and space id.

Examples

use quantized_density_fields::QDF;

// Creates 2d space with `9` as root state.
let (qdf, root) = QDF::new(2, 9);
assert_eq!(*qdf.space(root).state(), 9);

pub fn with_levels( dimensions: usize, state: S, levels: usize, ) -> (Self, Vec<ID>)

Creates new QDF information universe and increase its levels of density.

Arguments

• dimensions - Number of dimensions which space contains.
• state - State of space.
• levels - Number of levels of uniform density.

Returns

Tuple of new QDF object and vector of space ids.

Examples

use quantized_density_fields::{QDF, State};

// Creates 2d space with `27` as root state and 2 levels of uniform density.
let (qdf, spaces) = QDF::with_levels(2, 27, 2);
assert_eq!(spaces.len(), (qdf.dimensions() + 1).pow(2));
assert_eq!(*qdf.space(spaces[0]).state(), 3);
assert_eq!(
    State::merge(&qdf.spaces().map(|id| *qdf.space(*id).state()).collect::<Vec<i32>>()),
    27,
);

pub fn with_levels_and_minimum_state( dimensions: usize, state: S, levels: usize, ) -> (Self, Vec<ID>)

Creates new QDF information universe and increase its levels of density and state applied to lowest space lavel.

Arguments

• dimensions - Number of dimensions which space contains.
• state - State of space at lowest level.
• levels - Number of levels of uniform density.

Returns

Tuple of new QDF object and vector of space ids.

Examples

use quantized_density_fields::{QDF, State};

// Creates 2d space with `3` as lowest level state and 2 levels of uniform density.
let (qdf, spaces) = QDF::with_levels_and_minimum_state(2, 3, 2);
assert_eq!(spaces.len(), (qdf.dimensions() + 1).pow(2));
assert_eq!(*qdf.space(spaces[0]).state(), 3);
assert_eq!(
    State::merge(&qdf.spaces().map(|id| *qdf.space(*id).state()).collect::<Vec<i32>>()),
    27,
);

pub fn id(&self) -> ID

Gets QDF id.

pub fn dimensions(&self) -> usize

Gets QDF dimensions number.

Returns

Number of dimensions (axes) space has.

Examples

use quantized_density_fields::QDF;

let (qdf, _) = QDF::new(2, 9);
assert_eq!(qdf.dimensions(), 2);

pub fn space_exists(&self, id: ID) -> bool

Tells if space with given id exists in QDF.

Arguments

• id - space id.

Returns

true if given space exists, false otherwise.

Examples

use quantized_density_fields::QDF;

let (qdf, root) = QDF::new(2, 9);
assert!(qdf.space_exists(root));

pub fn spaces(&self) -> Iter<'_, ID>

Gets iterator over all spaces IDs.

Returns

Iterator over all space ids.

Examples

use quantized_density_fields::{QDF, ID};

let (mut qdf, root) = QDF::new(2, 9);
assert_eq!(qdf.spaces().count(), 1);
assert_eq!(*qdf.spaces().nth(0).unwrap(), root);
let (_, mut subs, _) = qdf.increase_space_density(root).unwrap();
subs.sort();
assert_eq!(qdf.spaces().count(), 3);
let mut spaces = qdf.spaces().cloned().collect::<Vec<ID>>();
spaces.sort();
assert_eq!(spaces, subs);

pub fn try_get_space(&self, id: ID) -> Option<&Space<S>>

Try to get given space.

Arguments

• id - space id.

Returns

Some reference to given Space data or None if space does not exists.

Examples

use quantized_density_fields::QDF;

let (qdf, root) = QDF::new(2, 9);
if let Some(space) = qdf.try_get_space(root) {
    assert_eq!(*space.state(), 9);
}

pub fn get_space(&self, id: ID) -> Result<&Space<S>>

Get given space or throw error if space does not exists.

Arguments

• id - space id.

Returns

Ok with reference to given Space data or Err if space does not exists.

Examples

use quantized_density_fields::QDF;

let (qdf, root) = QDF::new(2, 9);
if let Ok(space) = qdf.get_space(root) {
    assert_eq!(*space.state(), 9);
}

pub fn space(&self, id: ID) -> &Space<S>

Get given space or panic if space does not exists.

Arguments

• id - space id.

Returns

Reference to Space data.

Panics

When given space does not exists.

Examples

use quantized_density_fields::QDF;

let (qdf, root) = QDF::new(2, 9);
assert_eq!(*qdf.space(root).state(), 9);

pub fn try_set_space_state(&mut self, id: ID, state: S) -> bool

Try to set given space state.

Arguments

• id - space id.
• state - state.

Returns

true if space exists and state was successfuly set, false otherwise.

Examples

use quantized_density_fields::QDF;

let (mut qdf, root) = QDF::new(2, 9);
assert!(qdf.try_set_space_state(root, 3));

pub fn set_space_state(&mut self, id: ID, state: S) -> Result<()>

Set given space state or throw error if space does not exists.

Arguments

• id - space id.
• state - state.

Returns

Ok if space exists and state was successfuly set, Err otherwise.

Examples

use quantized_density_fields::QDF;

let (mut qdf, root) = QDF::new(2, 9);
assert!(qdf.set_space_state(root, 3).is_ok());

pub fn find_space_neighbors(&self, id: ID) -> Result<Vec<ID>>

Get list of IDs of given space neighbors or throws error if space does not exists.

Arguments

• id - space id.

Returns

Ok with vector of space neighbors if space exists, Err otherwise.

Examples

use quantized_density_fields::QDF;

let (mut qdf, root) = QDF::new(2, 9);
let (_, subs, _) = qdf.increase_space_density(root).unwrap();
assert_eq!(qdf.find_space_neighbors(subs[0]).unwrap(), vec![subs[1], subs[2]]);

pub fn find_path(&self, from: ID, to: ID) -> Result<Vec<ID>>

Gets list of space IDs that defines shortest path between two spaces, or throws error if space does not exists.

Arguments

• from - source space id.
• to - target space id.

Returns

Ok with space ids that builds shortest path between two points, Err if path cannot be found or spaces does not exists.

Examples

use quantized_density_fields::QDF;

let (mut qdf, root) = QDF::new(2, 9);
let (_, subs, _) = qdf.increase_space_density(root).unwrap();
let (_, subs2, _) = qdf.increase_space_density(subs[0]).unwrap();
assert_eq!(qdf.find_path(subs2[0], subs[2]).unwrap(), vec![subs2[0], subs2[1], subs[2]]);

pub fn increase_space_density( &mut self, id: ID, ) -> Result<(ID, Vec<ID>, Vec<(ID, ID)>)>

Increases given space density (subdivide space and rebind it properly to its neighbors), and returns process information (source space id, subdivided space ids, connections pairs) or throws error if space does not exists.

Arguments

• id - space id.

Returns

Ok with tuple of source space id, vector of subdivided space ids and vector of connections pairs or Err if space does not exists.

Examples

use quantized_density_fields::QDF;

let (mut qdf, root) = QDF::new(2, 9);
let (_, subs, _) = qdf.increase_space_density(root).unwrap();
assert_eq!(subs.len(), 3);

pub fn decrease_space_density( &mut self, id: ID, ) -> Result<Option<(Vec<ID>, ID)>>

Decreases given space density (merge space children and rebind them properly to theirs neighbors if space has 1 level of subdivision, otherwise perform this operation on its subspaces), and returns process information (source space ids, merged space id) or throws error if space does not exists.

Arguments

• id - space id.

Returns

Ok with Some tuple of vector of merged space ids and created space id, or Ok with None if space cannot be merged or Err if given space does not exists.

Examples

use quantized_density_fields::QDF;

let (mut qdf, root) = QDF::new(2, 9);
let (_, subs, _) = qdf.increase_space_density(root).unwrap();
assert_eq!(subs.len(), 3);
let (_, root) = qdf.decrease_space_density(subs[0]).unwrap().unwrap();
assert_eq!(qdf.spaces().len(), 1);
assert_eq!(*qdf.spaces().nth(0).unwrap(), root);

pub fn simulation_step<M>(&mut self)

where M: Simulate<S>,

Performs simulation step (go through all platonic spaces and modifies its states based on neighbor states). Actual state simulation is performed by your struct that implements Simulation trait.

pub fn simulation_step_parallel<M>(&mut self)

where M: Simulate<S>,

Does the same as simulation_step() but in parallel manner (it may or may not increase simulation performance if simulation is very complex).

pub fn simulate_states<M>(&self) -> Vec<(ID, S)>

where M: Simulate<S>,

Performs simulation on QDF like simulation_step() but instead of applying results to QDF, it returns simulated platonic space states along with their space ID.

Returns

Vector of tuples of id and its updated space that were simulated.

pub fn simulate_states_parallel<M>(&self) -> Vec<(ID, S)>

where M: Simulate<S>,

Performs simulation on QDF like simulation_step_parallel() but instead of applying results to QDF, it returns simulated platonic space states along with their space ID.

Returns

Vector of tuples of id and its updated space that were simulated.

Trait Implementations

impl<S> Debug for QDF<S>

where S: State + Debug,

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

Formats the value using the given formatter.