M-Labs
/
nalgebra
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Matrix market: Extend and reword documentation, rename some types

This commit is contained in:
Andreas Longva 2021-12-01 11:07:13 +01:00
parent 920bd75b82
commit 3b67afcd9b
2 changed files with 155 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

213
nalgebra-sparse/src/io/matrix_market.rs
View File

@ -27,11 +27,12 @@ pub struct MatrixMarketError {
} }
/// Errors produced by functions that expect well-formed matrix market format data. /// Errors produced by functions that expect well-formed matrix market format data.
/// > _NOTE:_ Since the matrix market design didn't mention if multiple sparse entries with the same coordiantes are allowed or not, so, it's allowed here.
#[non_exhaustive] #[non_exhaustive]
#[derive(Copy, Clone, Debug, PartialEq)] #[derive(Copy, Clone, Debug, PartialEq)]
pub enum MatrixMarketErrorKind { pub enum MatrixMarketErrorKind {
/// Indicates that some word is not known to MM format /// Parsing failure.
///
/// Indicates that the parser failed, for example due to an unexpected string.
/// ///
/// Examples /// Examples
/// -------- /// --------
@ -39,17 +40,17 @@ pub enum MatrixMarketErrorKind {
/// # use nalgebra_sparse::io::load_coo_from_matrix_market_str; /// # use nalgebra_sparse::io::load_coo_from_matrix_market_str;
/// # use nalgebra_sparse::io::MatrixMarketErrorKind; /// # use nalgebra_sparse::io::MatrixMarketErrorKind;
/// let str = r#" /// let str = r#"
/// %%MatrixMarket whatever whatever whatever whatever /// %%MatrixMarket invalid invalid invalid invalid
/// 1 1 1 /// 1 1 1
/// 1 1 5 /// 1 1 5
/// "#; /// "#;
/// let matrix_error = load_coo_from_matrix_market_str::<f64>(str); /// let matrix_result = load_coo_from_matrix_market_str::<f64>(str);
/// assert_eq!(matrix_error.is_err(), true); /// assert_eq!(matrix_result.is_err(), true);
/// assert_eq!(matrix_error.unwrap_err().kind(),MatrixMarketErrorKind::ParsingError); /// assert_eq!(matrix_result.unwrap_err().kind(), MatrixMarketErrorKind::ParsingError);
/// ``` /// ```
ParsingError, ParsingError,
/// Indicates that header is not valid /// Indicates that the matrix market header is invalid.
/// ///
/// Examples /// Examples
/// -------- /// --------
@ -62,13 +63,13 @@ pub enum MatrixMarketErrorKind {
/// 1 1 1 /// 1 1 1
/// 1 1 5 /// 1 1 5
/// "#; /// "#;
/// let matrix_error = load_coo_from_matrix_market_str::<f64>(str); /// let matrix_result = load_coo_from_matrix_market_str::<f64>(str);
/// assert_eq!(matrix_error.is_err(), true); /// assert_eq!(matrix_result.is_err(), true);
/// assert_eq!(matrix_error.unwrap_err().kind(),MatrixMarketErrorKind::InvalidHeader); /// assert_eq!(matrix_result.unwrap_err().kind(),MatrixMarketErrorKind::InvalidHeader);
/// ``` /// ```
InvalidHeader, InvalidHeader,
/// Indicates that the data entries in .mtx file are more or less than entries specified in .mtx file /// Indicates that the number of data entries in the matrix market file does not match the header.
/// ///
/// Examples /// Examples
/// -------- /// --------
@ -82,13 +83,14 @@ pub enum MatrixMarketErrorKind {
/// 2 2 2 /// 2 2 2
/// 2 3 2 /// 2 3 2
/// "#; /// "#;
/// let matrix_error = load_coo_from_matrix_market_str::<f64>(str); /// let matrix_result = load_coo_from_matrix_market_str::<f64>(str);
/// assert_eq!(matrix_error.is_err(), true); /// assert_eq!(matrix_result.is_err(), true);
/// assert_eq!(matrix_error.unwrap_err().kind(),MatrixMarketErrorKind::EntryNumUnmatched); /// assert_eq!(matrix_result.unwrap_err().kind(),MatrixMarketErrorKind::EntryMismatch);
/// ``` /// ```
EntryNumUnmatched, EntryMismatch,
/// Indicates that the type T is not matched with the function it called. /// Indicates that the scalar type requested is not compatible with the scalar type stored
/// in the matrix market file.
/// ///
/// Examples /// Examples
/// -------- /// --------
@ -97,18 +99,20 @@ pub enum MatrixMarketErrorKind {
/// # use nalgebra_sparse::io::MatrixMarketErrorKind; /// # use nalgebra_sparse::io::MatrixMarketErrorKind;
/// let str = r#" /// let str = r#"
/// %%matrixmarket matrix coordinate real general /// %%matrixmarket matrix coordinate real general
/// % it should be called by load_coo_from_matrix_market_str::<f64>(str), or f32; /// % it should be loaded with load_coo_from_matrix_market_str::<f64>(str) (or f32)
/// 3 3 2 /// 3 3 2
/// 2 2 2.22 /// 2 2 2.22
/// 2 3 2.22 /// 2 3 2.22
/// "#; /// "#;
/// let matrix_error = load_coo_from_matrix_market_str::<i32>(str); /// let matrix_result = load_coo_from_matrix_market_str::<i32>(str);
/// assert_eq!(matrix_error.is_err(), true); /// assert_eq!(matrix_result.is_err(), true);
/// assert_eq!(matrix_error.unwrap_err().kind(),MatrixMarketErrorKind::TypeUnmatched); /// assert_eq!(matrix_result.unwrap_err().kind(),MatrixMarketErrorKind::TypeMismatch);
/// ``` /// ```
TypeUnmatched, TypeMismatch,
/// Indicates that zero has been used as an index in the data, or the shape of the matrix, which is not allowed. /// Indicates that zero has been used as an index in the data.
///
/// **Note**: The matrix market format uses 1-based indexing.
/// ///
/// Examples /// Examples
/// -------- /// --------
@ -120,13 +124,14 @@ pub enum MatrixMarketErrorKind {
/// 1 1 1 /// 1 1 1
/// 0 0 10 /// 0 0 10
/// "#; /// "#;
/// let matrix_error = load_coo_from_matrix_market_str::<f64>(str); /// let matrix_result = load_coo_from_matrix_market_str::<f64>(str);
/// assert_eq!(matrix_error.is_err(), true); /// assert_eq!(matrix_result.is_err(), true);
/// assert_eq!(matrix_error.unwrap_err().kind(),MatrixMarketErrorKind::ZeroError); /// assert_eq!(matrix_result.unwrap_err().kind(),MatrixMarketErrorKind::ZeroError);
/// ``` /// ```
ZeroError, ZeroError,
/// Indicates [SparseFormatError], while creating the sparse matrix. /// Indicates [SparseFormatError] while creating the sparse matrix.
///
/// ///
/// Examples /// Examples
/// -------- /// --------
@ -139,13 +144,14 @@ pub enum MatrixMarketErrorKind {
/// 1 1 1 /// 1 1 1
/// 4 2 10 /// 4 2 10
/// "#; /// "#;
/// let matrix_error = load_coo_from_matrix_market_str::<f64>(str); /// let matrix_result = load_coo_from_matrix_market_str::<f64>(str);
/// assert_eq!(matrix_error.is_err(), true); /// assert_eq!(matrix_result.is_err(), true);
/// assert_eq!(matrix_error.unwrap_err().kind(),MatrixMarketErrorKind::SparseFormatError(SparseFormatErrorKind::IndexOutOfBounds)); /// assert_eq!(matrix_result.unwrap_err().kind(),
/// MatrixMarketErrorKind::SparseFormatError(SparseFormatErrorKind::IndexOutOfBounds));
/// ``` /// ```
SparseFormatError(SparseFormatErrorKind), SparseFormatError(SparseFormatErrorKind),
/// Indicates that a wrong diagonal element has been provieded to the matrix /// Indicates that a wrong diagonal element has been provided to the matrix.
/// ///
/// Examples /// Examples
/// -------- /// --------
@ -160,9 +166,9 @@ pub enum MatrixMarketErrorKind {
/// 1 1 10 /// 1 1 10
/// 2 1 5 /// 2 1 5
/// "#; /// "#;
/// let matrix_error = load_coo_from_matrix_market_str::<f64>(str); /// let matrix_result = load_coo_from_matrix_market_str::<f64>(str);
/// assert_eq!(matrix_error.is_err(), true); /// assert_eq!(matrix_result.is_err(), true);
/// assert_eq!(matrix_error.unwrap_err().kind(),MatrixMarketErrorKind::DiagonalError); /// assert_eq!(matrix_result.unwrap_err().kind(),MatrixMarketErrorKind::DiagonalError);
/// ///
/// let str = r#" /// let str = r#"
/// %%matrixmarket matrix coordinate complex hermitian /// %%matrixmarket matrix coordinate complex hermitian
@ -171,28 +177,27 @@ pub enum MatrixMarketErrorKind {
/// 1 1 10 2 /// 1 1 10 2
/// 2 1 5 2 /// 2 1 5 2
/// "#; /// "#;
/// let matrix_error = load_coo_from_matrix_market_str::<Complex<f64>>(str); /// let matrix_result = load_coo_from_matrix_market_str::<Complex<f64>>(str);
/// assert_eq!(matrix_error.is_err(), true); /// assert_eq!(matrix_result.is_err(), true);
/// assert_eq!(matrix_error.unwrap_err().kind(),MatrixMarketErrorKind::DiagonalError); /// assert_eq!(matrix_result.unwrap_err().kind(),MatrixMarketErrorKind::DiagonalError);
/// ``` /// ```
/// Here the skew matrix shouldn't have an element on the diagonal /// Here the skew matrix shouldn't have an element on the diagonal.
DiagonalError, DiagonalError,
/// Indicates [io error](`std::io::Error`), while reading the data from file. /// Indicates an [IO error](`std::io::Error`) while reading the data from file.
/// ///
/// Examples /// Examples
/// -------- /// --------
/// ```rust /// ```rust
/// # use nalgebra_sparse::io::load_coo_from_matrix_market_file; /// # use nalgebra_sparse::io::load_coo_from_matrix_market_file;
/// # use nalgebra_sparse::io::MatrixMarketErrorKind; /// # use nalgebra_sparse::io::MatrixMarketErrorKind;
/// let file_name = "whatever.mtx"; /// let matrix_result = load_coo_from_matrix_market_file::<f64,_>("matrix.mtx");
/// let matrix_error = load_coo_from_matrix_market_file::<f64,_>(file_name); /// assert_eq!(matrix_result.is_err(), true);
/// assert_eq!(matrix_error.is_err(), true); /// assert_eq!(matrix_result.unwrap_err().kind(),MatrixMarketErrorKind::IOError(std::io::ErrorKind::NotFound));
/// assert_eq!(matrix_error.unwrap_err().kind(),MatrixMarketErrorKind::IOError(std::io::ErrorKind::NotFound));
/// ``` /// ```
IOError(std::io::ErrorKind), IOError(std::io::ErrorKind),
/// Indicates (skew-)symmetric (or hermitian) matrix is not lower triangle matrix. /// Indicates that a (skew-)symmetric (or hermitian) matrix is not a lower triangular matrix.
/// ///
/// Examples /// Examples
/// -------- /// --------
@ -205,13 +210,13 @@ pub enum MatrixMarketErrorKind {
/// 1 1 10 /// 1 1 10
/// 2 3 5 /// 2 3 5
/// "#; /// "#;
/// let matrix_error = load_coo_from_matrix_market_str::<i32>(str); /// let matrix_result = load_coo_from_matrix_market_str::<i32>(str);
/// assert_eq!(matrix_error.is_err(), true); /// assert_eq!(matrix_result.is_err(), true);
/// assert_eq!(matrix_error.unwrap_err().kind(),MatrixMarketErrorKind::NotLowerTriangle); /// assert_eq!(matrix_result.unwrap_err().kind(),MatrixMarketErrorKind::NotLowerTriangle);
/// ``` /// ```
NotLowerTriangle, NotLowerTriangle,
/// Indicates (skew-)symmetric (or hermitian) matrix is not square matrix. /// Indicates that a (skew-)symmetric (or hermitian) matrix is not a square matrix.
/// ///
/// Examples /// Examples
/// -------- /// --------
@ -224,11 +229,11 @@ pub enum MatrixMarketErrorKind {
/// 1 1 10 /// 1 1 10
/// 2 3 5 /// 2 3 5
/// "#; /// "#;
/// let matrix_error = load_coo_from_matrix_market_str::<i32>(str); /// let matrix_result = load_coo_from_matrix_market_str::<i32>(str);
/// assert_eq!(matrix_error.is_err(), true); /// assert_eq!(matrix_result.is_err(), true);
/// assert_eq!(matrix_error.unwrap_err().kind(),MatrixMarketErrorKind::NotSquareMatrix); /// assert_eq!(matrix_result.unwrap_err().kind(),MatrixMarketErrorKind::NonSquare);
/// ``` /// ```
NotSquareMatrix, NonSquare,
} }
impl MatrixMarketError { impl MatrixMarketError {
@ -239,7 +244,7 @@ impl MatrixMarketError {
} }
} }
/// The operation error kind. /// The matrix market error kind.
#[must_use] #[must_use]
pub fn kind(&self) -> MatrixMarketErrorKind { pub fn kind(&self) -> MatrixMarketErrorKind {
self.error_kind self.error_kind
@ -254,7 +259,7 @@ impl MatrixMarketError {
impl fmt::Display for MatrixMarketError { impl fmt::Display for MatrixMarketError {
fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
write!(f, "Matrix Market load error: ")?; write!(f, "Matrix Market error: ")?;
match self.kind() { match self.kind() {
MatrixMarketErrorKind::ParsingError => { MatrixMarketErrorKind::ParsingError => {
write!(f, "ParsingError,")?; write!(f, "ParsingError,")?;
@ -262,11 +267,11 @@ impl fmt::Display for MatrixMarketError {
MatrixMarketErrorKind::InvalidHeader => { MatrixMarketErrorKind::InvalidHeader => {
write!(f, "InvalidHeader,")?; write!(f, "InvalidHeader,")?;
} }
MatrixMarketErrorKind::EntryNumUnmatched => { MatrixMarketErrorKind::EntryMismatch => {
write!(f, "EntryNumUnmatched,")?; write!(f, "EntryNumUnmatched,")?;
} }
MatrixMarketErrorKind::TypeUnmatched => { MatrixMarketErrorKind::TypeMismatch => {
write!(f, "TypeUnmatched,")?; write!(f, "TypeMismatch,")?;
} }
MatrixMarketErrorKind::SparseFormatError(_) => { MatrixMarketErrorKind::SparseFormatError(_) => {
write!(f, "SparseFormatError,")?; write!(f, "SparseFormatError,")?;
@ -283,11 +288,11 @@ impl fmt::Display for MatrixMarketError {
MatrixMarketErrorKind::NotLowerTriangle => { MatrixMarketErrorKind::NotLowerTriangle => {
write!(f, "NotLowerTriangle,")?; write!(f, "NotLowerTriangle,")?;
} }
MatrixMarketErrorKind::NotSquareMatrix => { MatrixMarketErrorKind::NonSquare => {
write!(f, "NotSquareMatrix,")?; write!(f, "NotSquareMatrix,")?;
} }
} }
write!(f, " Message: {}", self.message) write!(f, " message: {}", self.message)
} }
} }
@ -334,9 +339,9 @@ impl From<std::io::Error> for MatrixMarketError {
impl From<TryFromIntError> for MatrixMarketError { impl From<TryFromIntError> for MatrixMarketError {
fn from(err: TryFromIntError) -> Self { fn from(err: TryFromIntError) -> Self {
Self::from_kind_and_message( Self::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!( format!(
"Please consider using a larger integery type. Error message: {}", "Please consider using a larger integer type. Error message: {}",
&err &err
), ),
) )
@ -348,7 +353,7 @@ impl From<TryFromIntError> for MatrixMarketError {
impl From<Infallible> for MatrixMarketError { impl From<Infallible> for MatrixMarketError {
fn from(_err: Infallible) -> Self { fn from(_err: Infallible) -> Self {
Self::from_kind_and_message( Self::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("This won't happen"), format!("This won't happen"),
) )
} }
@ -479,9 +484,9 @@ fn typecode_precheck(tc: &Typecode) -> Result<(), MatrixMarketError> {
} }
} }
/// Base trait for matrix market types. /// Scalar types supported by the matrix market parser.
pub trait MatrixMarketScalar: Scalar { pub trait MatrixMarketScalar: Scalar {
/// When matrix is an Integer matrix, it will convert a [i128] number to this type. /// When the matrix is an integer matrix, it will convert a [i128] number to this type.
fn from_i128(i: i128) -> Result<Self, MatrixMarketError>; fn from_i128(i: i128) -> Result<Self, MatrixMarketError>;
/// When matrix is a Real matrix, it will convert a [f64] number to this type. /// When matrix is a Real matrix, it will convert a [f64] number to this type.
fn from_f64(f: f64) -> Result<Self, MatrixMarketError>; fn from_f64(f: f64) -> Result<Self, MatrixMarketError>;
@ -494,6 +499,7 @@ pub trait MatrixMarketScalar: Scalar {
/// When matrix is a Hermitian matrix, it will convert itself to its conjugate. /// When matrix is a Hermitian matrix, it will convert itself to its conjugate.
fn conjugate(self) -> Result<Self, MatrixMarketError>; fn conjugate(self) -> Result<Self, MatrixMarketError>;
} }
/// Implement MatrixMarketScalar for primitive integer types. /// Implement MatrixMarketScalar for primitive integer types.
macro_rules! mm_int_impl { macro_rules! mm_int_impl {
($T:ty) => { ($T:ty) => {
@ -505,28 +511,28 @@ macro_rules! mm_int_impl {
#[inline] #[inline]
fn from_f64(_f: f64) -> Result<Self, MatrixMarketError> { fn from_f64(_f: f64) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("Int type can't be parsed from f64"), format!("Int type can't be parsed from f64"),
)) ))
} }
#[inline] #[inline]
fn from_c64(_c: Complex<f64>) -> Result<Self, MatrixMarketError> { fn from_c64(_c: Complex<f64>) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("Int type can't be parsed from Complex<f64>"), format!("Int type can't be parsed from Complex<f64>"),
)) ))
} }
#[inline] #[inline]
fn from_pattern(_p: ()) -> Result<Self, MatrixMarketError> { fn from_pattern(_p: ()) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("Int type can't be parsed from ()"), format!("Int type can't be parsed from ()"),
)) ))
} }
#[inline] #[inline]
fn conjugate(self) -> Result<Self, MatrixMarketError> { fn conjugate(self) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("Int type has no conjugate"), format!("Int type has no conjugate"),
)) ))
} }
@ -544,7 +550,7 @@ macro_rules! mm_real_impl {
#[inline] #[inline]
fn from_i128(_i: i128) -> Result<Self, MatrixMarketError> { fn from_i128(_i: i128) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("real type can't be parsed from i128"), format!("real type can't be parsed from i128"),
)) ))
} }
@ -555,21 +561,21 @@ macro_rules! mm_real_impl {
#[inline] #[inline]
fn from_c64(_c: Complex<f64>) -> Result<Self, MatrixMarketError> { fn from_c64(_c: Complex<f64>) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("real type can't be parsed from Complex<f64>"), format!("real type can't be parsed from Complex<f64>"),
)) ))
} }
#[inline] #[inline]
fn from_pattern(_p: ()) -> Result<Self, MatrixMarketError> { fn from_pattern(_p: ()) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("real type can't be parsed from ()"), format!("real type can't be parsed from ()"),
)) ))
} }
#[inline] #[inline]
fn conjugate(self) -> Result<Self, MatrixMarketError> { fn conjugate(self) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("real type has no conjugate"), format!("real type has no conjugate"),
)) ))
} }
@ -580,6 +586,7 @@ macro_rules! mm_real_impl {
} }
}; };
} }
/// Implement MatrixMarketScalar for primitive complex types. /// Implement MatrixMarketScalar for primitive complex types.
macro_rules! mm_complex_impl { macro_rules! mm_complex_impl {
($T:ty) => { ($T:ty) => {
@ -587,14 +594,14 @@ macro_rules! mm_complex_impl {
#[inline] #[inline]
fn from_i128(_i: i128) -> Result<Self, MatrixMarketError> { fn from_i128(_i: i128) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("Complex type can't be parsed from i128"), format!("Complex type can't be parsed from i128"),
)) ))
} }
#[inline] #[inline]
fn from_f64(_f: f64) -> Result<Self, MatrixMarketError> { fn from_f64(_f: f64) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("Complex type can't be parsed from f64"), format!("Complex type can't be parsed from f64"),
)) ))
} }
@ -608,7 +615,7 @@ macro_rules! mm_complex_impl {
#[inline] #[inline]
fn from_pattern(_p: ()) -> Result<Self, MatrixMarketError> { fn from_pattern(_p: ()) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("Complex type can't be parsed from ()"), format!("Complex type can't be parsed from ()"),
)) ))
} }
@ -630,21 +637,21 @@ macro_rules! mm_pattern_impl {
#[inline] #[inline]
fn from_i128(_i: i128) -> Result<Self, MatrixMarketError> { fn from_i128(_i: i128) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("Pattern type can't be parsed from i128"), format!("Pattern type can't be parsed from i128"),
)) ))
} }
#[inline] #[inline]
fn from_f64(_f: f64) -> Result<Self, MatrixMarketError> { fn from_f64(_f: f64) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("Pattern type can't be parsed from f64"), format!("Pattern type can't be parsed from f64"),
)) ))
} }
#[inline] #[inline]
fn from_c64(_c: Complex<f64>) -> Result<Self, MatrixMarketError> { fn from_c64(_c: Complex<f64>) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("Pattern type can't be parsed from Complex<f64>"), format!("Pattern type can't be parsed from Complex<f64>"),
)) ))
} }
@ -656,14 +663,14 @@ macro_rules! mm_pattern_impl {
#[inline] #[inline]
fn conjugate(self) -> Result<Self, MatrixMarketError> { fn conjugate(self) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("Pattern type has no conjugate"), format!("Pattern type has no conjugate"),
)) ))
} }
#[inline] #[inline]
fn negative(self) -> Result<Self, MatrixMarketError> { fn negative(self) -> Result<Self, MatrixMarketError> {
Err(MatrixMarketError::from_kind_and_message( Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::TypeUnmatched, MatrixMarketErrorKind::TypeMismatch,
format!("Pattern type has no negative"), format!("Pattern type has no negative"),
)) ))
} }
@ -687,16 +694,31 @@ mm_pattern_impl!(());
#[derive(Parser)] #[derive(Parser)]
#[grammar = "io/matrix_market.pest"] #[grammar = "io/matrix_market.pest"]
struct MMParser; struct MatrixMarketParser;
/// Parses a Matrix Market file at the given path, and returns the corresponding sparse matrix as CooMatrix format. /// Parses a Matrix Market file at the given path as a `CooMatrix`.
///
/// The matrix market format specification does not clarify whether duplicate entries are allowed. Our importer
/// assumes that this is permitted and produces a `CooMatrix` with possibly duplicate entries.
///
/// **Note**: A current restriction of the importer is that you must use a compatible scalar type when importing.
/// For example, in order to import a matrix stored as `integer` in the matrix market format, you must
/// import it as an integer matrix, otherwise a [TypeMismatch](MatrixMarketErrorKind::TypeMismatch) error
/// will be returned. This restriction may be lifted in the future, and is
/// tracked by issue [#1038](https://github.com/dimforge/nalgebra/issues/1038).
/// ///
/// Errors /// Errors
/// -------- /// --------
/// ///
/// See [MatrixMarketErrorKind] for a list of possible error conditions. /// See [MatrixMarketErrorKind] for a list of possible error conditions.
/// ///
/// > _NOTE:_ Here uses strong type requirements, which means if the matrix is an integer matrix, e.g. `%%matrixmarket matrix cooridnate integer general`, then you have to load it by `load_coo_from_matrix_market_file<T>`, where T is an integer type. Trying `load_coo_from_matrix_market_file<f64>` will give [TypeUnmatched](MatrixMarketErrorKind::TypeUnmatched) Error. After loading it, you can cast it into a `f64` matrix, by calling [cast](`nalgebra::base::Matrix::cast()`), but be aware of accuracy lose. /// Examples
/// --------
/// ```
/// use nalgebra_sparse::io::load_coo_from_matrix_market_file;
/// // Use e.g. `f64` for floating-point matrices
/// let matrix = load_coo_from_matrix_market_file::<i32>("path/to/matrix.mtx")?;
/// ```
pub fn load_coo_from_matrix_market_file<T, P: AsRef<Path>>( pub fn load_coo_from_matrix_market_file<T, P: AsRef<Path>>(
path: P, path: P,
) -> Result<CooMatrix<T>, MatrixMarketError> ) -> Result<CooMatrix<T>, MatrixMarketError>
@ -707,21 +729,34 @@ where
load_coo_from_matrix_market_str(&file) load_coo_from_matrix_market_str(&file)
} }
/// Parses a Matrix Market file described by the given string, and returns the corresponding as CooMatrix format. /// Parses a Matrix Market file described by the given string as a `CooMatrix`.
///
/// See [load_coo_from_matrix_market_file] for more information.
/// ///
/// Errors /// Errors
/// -------- /// --------
/// ///
/// See [MatrixMarketErrorKind] for a list of possible error conditions. /// See [MatrixMarketErrorKind] for a list of possible error conditions.
/// ///
/// > _NOTE:_ Here uses strong type requirements, which means if the matrix is an integer matrix, e.g. `%%matrixmarket matrix cooridnate integer general`, then you have to load it by `load_coo_from_matrix_market_str<T>`, where T is an integer type. Trying `load_coo_from_matrix_market_str<f64>` will give [TypeUnmatched](MatrixMarketErrorKind::TypeUnmatched) Error. After loading it, you can cast it into a `f64` matrix, by calling [cast](`nalgebra::base::Matrix::cast()`),but be aware of accuracy lose. /// Examples
/// --------
/// ```
/// # use nalgebra_sparse::io::load_coo_from_matrix_market_str;
/// # use nalgebra_sparse::io::MatrixMarketErrorKind;
/// let str = r#"
/// %%matrixmarket matrix coordinate integer symmetric
/// 5 4 2
/// 1 1 10
/// 2 3 5
/// "#;
/// let matrix = load_coo_from_matrix_market_str::<i32>(str)?;
/// ```
pub fn load_coo_from_matrix_market_str<T>(data: &str) -> Result<CooMatrix<T>, MatrixMarketError> pub fn load_coo_from_matrix_market_str<T>(data: &str) -> Result<CooMatrix<T>, MatrixMarketError>
where where
T: MatrixMarketScalar, T: MatrixMarketScalar,
{ {
// unwrap() in this function are guaranteed by parsing the data // unwrap() in this function are guaranteed by parsing the data
let file = MMParser::parse(Rule::Document, data)?.next().unwrap(); let file = MatrixMarketParser::parse(Rule::Document, data)?.next().unwrap();
let mut rows: Vec<usize> = Vec::new(); let mut rows: Vec<usize> = Vec::new();
let mut cols: Vec<usize> = Vec::new(); let mut cols: Vec<usize> = Vec::new();
@ -755,7 +790,7 @@ where
let count = lines.clone().count(); let count = lines.clone().count();
if count != shape.2 { if count != shape.2 {
return Err(MatrixMarketError::from_kind_and_message( return Err(MatrixMarketError::from_kind_and_message(
MatrixMarketErrorKind::EntryNumUnmatched, MatrixMarketErrorKind::EntryMismatch,
format!( format!(
"{} entries required for the matrix, but {} was provided", "{} entries required for the matrix, but {} was provided",
shape.2, count, shape.2, count,
@ -996,7 +1031,7 @@ fn parse_sparse_shape(
// check for square matirx, when it's not a general matrix // check for square matirx, when it's not a general matrix
if *storagescheme != StorageScheme::General && r != c { if *storagescheme != StorageScheme::General && r != c {
return Err(MatrixMarketError::from_kind_and_message(MatrixMarketErrorKind::NotSquareMatrix,format!("(Skew-)Symmetric or hermitian matrix should be square matrix, but it has dimension {} and {}",r,c))); return Err(MatrixMarketError::from_kind_and_message(MatrixMarketErrorKind::NonSquare, format!("(Skew-)Symmetric or hermitian matrix should be square matrix, but it has dimension {} and {}", r, c)));
} }
Ok((r, c, nnz)) Ok((r, c, nnz))
@ -1032,7 +1067,7 @@ fn parse_dense_shape(
// check for square matirx, when it's not a general matrix // check for square matirx, when it's not a general matrix
if *storagescheme != StorageScheme::General && r != c { if *storagescheme != StorageScheme::General && r != c {
return Err(MatrixMarketError::from_kind_and_message(MatrixMarketErrorKind::NotSquareMatrix,format!("(Skew-)Symmetric or hermitian matrix should be square matrix, but it has dimension {} and {}",r,c))); return Err(MatrixMarketError::from_kind_and_message(MatrixMarketErrorKind::NonSquare, format!("(Skew-)Symmetric or hermitian matrix should be square matrix, but it has dimension {} and {}", r, c)));
} }
let n: usize; let n: usize;

34
nalgebra-sparse/src/io/mod.rs
View File

@ -1,7 +1,35 @@
//! Parsers for various matrix formats. //! Functionality for importing and exporting sparse matrices to and from files.
//! //!
//! ## Matrix Market //! **Available only when the `io` feature is enabled.**
//! See the [website](https://math.nist.gov/MatrixMarket/formats.html) or the [paper](https://www.researchgate.net/publication/2630533_The_Matrix_Market_Exchange_Formats_Initial_Design) for more details about matrix market. //!
//! The following formats are currently supported:
//!
//! | Format | Import | Export |
//! | ------------------------------------------------|------------|------------|
//! | [Matrix market](#matrix-market-format) | Yes | No |
//!
//! [Matrix market]: https://math.nist.gov/MatrixMarket/formats.html
//!
//! ## Matrix Market format
//!
//! The Matrix Market format is a simple ASCII-based file format for sparse matrices, and was initially developed for
//! the [NIST Matrix Market](https://math.nist.gov/MatrixMarket/), a repository of example sparse matrices.
//! In later years it has largely been superseded by the
//! [SuiteSparse Matrix Collection](https://sparse.tamu.edu/) (formerly University of Florida Sparse Matrix Collection),
//! which also uses the Matrix Market file format.
//!
//! We currently offer functionality for importing a Matrix market file to an instance of a
//! [CooMatrix](crate::CooMatrix) through the function [load_coo_from_matrix_market_file]. It is also possible to load
//! a matrix stored in the matrix market format with the function [load_coo_from_matrix_market_str].
//!
//! Export is currently not implemented, but [planned](https://github.com/dimforge/nalgebra/issues/1037).
//!
//! Our implementation is based on the [format description](https://math.nist.gov/MatrixMarket/formats.html)
//! on the Matrix Market website and the
//! [following NIST whitepaper](https://math.nist.gov/MatrixMarket/reports/MMformat.ps):
//!
//! > Boisvert, Ronald F., Roldan Pozo, and Karin A. Remington.<br/>
//! > "*The Matrix Market Exchange Formats: Initial Design.*" (1996).
pub use self::matrix_market::{ pub use self::matrix_market::{
load_coo_from_matrix_market_file, load_coo_from_matrix_market_str, MatrixMarketError, load_coo_from_matrix_market_file, load_coo_from_matrix_market_str, MatrixMarketError,