1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
use super::{normalization, NormalizationMethod, ResidualsValues};
use std::fmt;

/// Single residual configuration
///
/// A residual is constituded of two elements:
/// - the way of computing the `stopping_critera` from the left and right part of a residual
/// - the way of computing the error for the update (`update_method`) used by the rootfinder
#[derive(Debug, Copy, Clone, PartialEq)]
pub struct ResidualConfig {
    stopping_critera: NormalizationMethod,
    update_method: NormalizationMethod,
}

impl Default for ResidualConfig {
    fn default() -> ResidualConfig {
        ResidualConfig {
            stopping_critera: NormalizationMethod::Abs,
            update_method: NormalizationMethod::Abs,
        }
    }
}

impl ResidualConfig {
    pub fn new(stopping_critera: NormalizationMethod, update_method: NormalizationMethod) -> Self {
        ResidualConfig {
            stopping_critera,
            update_method,
        }
    }

    pub fn get_update_method(self) -> NormalizationMethod {
        self.update_method
    }
    pub fn get_stopping_criteria(self) -> NormalizationMethod {
        self.stopping_critera
    }
}

/// Residuals configuration used by the solver
///
/// The solver is using directly two slices to perform its calculation
/// - the `update_methods` used for computing the jacobian
/// - the `stopping_criterias` used to control if another iteration is performed
///
/// It is possible to used a `Vec<ResidualConfig>` to create such a struct thanks to the `convert_into_vecs()` method.
///
/// However, if the performance is critical for the user,
/// it should create is own arrays to feed to the `new()` constructor
/// and not use `ResidualConfig` (singular)
#[derive(Debug, PartialEq)]
pub struct ResidualsConfig<'a> {
    stopping_criterias: &'a [NormalizationMethod],
    update_methods: &'a [NormalizationMethod],
    length: usize,
}

impl<'a> ResidualsConfig<'a> {
    pub fn new(
        stopping_criterias: &'a [NormalizationMethod],
        update_methods: &'a [NormalizationMethod],
    ) -> Self {
        let length = stopping_criterias.len();
        if stopping_criterias.len() != update_methods.len() {
            panic!(
                "Dimension mismatch between stopping_criteras and update_methods {} != {}",
                stopping_criterias.len(),
                update_methods.len()
            );
        }

        ResidualsConfig {
            stopping_criterias,
            update_methods,
            length,
        }
    }

    /// Method to generate the vector of `stopping_criteras` and `update_methods` from a vector of `ResidualConfig`
    pub fn convert_into_vecs(
        residuals_config: Vec<ResidualConfig>,
    ) -> (Vec<NormalizationMethod>, Vec<NormalizationMethod>) {
        let length = residuals_config.len();
        let mut stopping_criterias = Vec::with_capacity(length);
        let mut update_methods = Vec::with_capacity(length);

        for elt in residuals_config {
            stopping_criterias.push(elt.get_stopping_criteria());
            update_methods.push(elt.get_update_method());
        }

        (stopping_criterias, update_methods)
    }

    pub fn len(&self) -> usize {
        self.length
    }

    /// Evaluation of the value of the update residuals thanks to the `normalization()` function
    pub fn evaluate_update_residuals<D>(
        &self,
        values: &ResidualsValues<D>,
    ) -> nalgebra::OVector<f64, D>
    where
        D: nalgebra::Dim,
        nalgebra::DefaultAllocator: nalgebra::base::allocator::Allocator<f64, D>,
    {
        let mut update_residuals: nalgebra::OVector<f64, D> =
            super::super::ovector_zeros_from_shape(values.shape());

        for (i, &update_method) in self.update_methods.iter().enumerate() {
            let (left, right) = values.get_values(i);
            update_residuals[i] = normalization(left, right, update_method);
        }
        update_residuals
    }

    /// Evaluation of the value of the stopping residuals thanks to the `normalization()` function
    pub fn evaluate_stopping_residuals<D>(
        &self,
        values: &ResidualsValues<D>,
    ) -> nalgebra::OVector<f64, D>
    where
        D: nalgebra::Dim,
        nalgebra::DefaultAllocator: nalgebra::base::allocator::Allocator<f64, D>,
    {
        let mut stopping_residuals: nalgebra::OVector<f64, D> =
            super::super::ovector_zeros_from_shape(values.shape());

        for (i, &stopping_criteria) in self.stopping_criterias.iter().enumerate() {
            let (left, right) = values.get_values(i);
            stopping_residuals[i] = normalization(left, right, stopping_criteria).abs();
        }
        stopping_residuals
    }

    pub fn get_update_methods(&self) -> &'a [NormalizationMethod] {
        self.update_methods
    }

    pub fn get_stopping_criterias(&self) -> &'a [NormalizationMethod] {
        self.stopping_criterias
    }
}

impl<'a> fmt::Display for ResidualsConfig<'a> {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        let separation_line = String::from(
            "+-------------------+--------------------------+--------------------------+\n",
        );

        let mut content = String::from("Residuals configuration\n");
        content.push_str("=======================\n\n");
        content.push_str(&separation_line);
        content.push_str("| ");
        content.push_str(&format!("{:width$}", "Residual number", width = 18));
        content.push_str("| ");
        content.push_str(&format!("{:width$}", "Stopping criteria", width = 25));
        content.push_str("| ");
        content.push_str(&format!("{:width$}", "Update method", width = 25));
        content.push_str("|\n");

        content.push_str(&separation_line);

        for i in 0..self.len() {
            content.push_str(&format!("| {:width$}", &i.to_string(), width = 18));
            content.push_str("| ");
            content.push_str(&format!(
                "{:width$}",
                self.stopping_criterias[i].to_string(),
                width = 25
            ));
            content.push_str("| ");
            content.push_str(&format!(
                "{:width$}|",
                self.update_methods[i].to_string(),
                width = 25
            ));
            content.push('\n');
        }
        content.push_str(&separation_line);
        content.push('\n');
        write!(f, "{}", content)
    }
}