Yog.IO.MatrixMarket (YogEx v1.0.0)

Copy Markdown View Source

Matrix Market (.mtx) format serialization support.

Provides functions to serialize and deserialize graphs in the Matrix Market exchange format, a common format for sharing sparse and dense matrices in scientific computing and graph theory.

Format Overview

Matrix Market files start with a header: %%MatrixMarket matrix <format> <field> <symmetry>

  • Format: coordinate (sparse) or array (dense) - Currently coordinate is primary.
  • Field: real, integer, pattern, or complex.
  • Symmetry: general, symmetric, skew-symmetric, or hermitian.

For graph representation:

  • Rows and Columns represent nodes.
  • Matrix indices are 1-based.
  • Symmetric matrices are often used for undirected graphs.

Example

iex> graph = Yog.directed()
...> |> Yog.add_node(1, nil)
...> |> Yog.add_node(2, nil)
...> |> Yog.add_edge_ensure(from: 1, to: 2, with: 5.0)
iex>
iex> mtx_string = Yog.IO.MatrixMarket.serialize(graph)
iex> String.contains?(mtx_string, "%%MatrixMarket matrix coordinate real general")
true
iex> String.contains?(mtx_string, "1 2 5.0")
true

Default Configurations

Default behavior:

  • Node data: Ignored during serialization (Matrix Market only stores matrix values)
  • Edge weights: Converted to float or integer

Summary

Functions

default_options()

Returns default Matrix Market serialization options.

options_with(weight_formatter, opts \\ [])

Creates Matrix Market options with custom configurations.

parse(input, g_type \\ nil)

Parses a Matrix Market string into a graph.

parse_with(input, g_type, node_parser, edge_parser)

Parses a Matrix Market string with custom node and edge parsers.

read(path, g_type \\ nil)

Reads a graph from a Matrix Market file.

read_with(path, g_type, node_parser, edge_parser)

Reads a graph from a Matrix Market file with custom parsers.

serialize(graph)

Serializes a graph to Matrix Market coordinate format.

serialize_with(options, graph)

Serializes a graph to Matrix Market format with custom options.

write(path, graph)

Writes a graph to a Matrix Market file.

write_with(path, options, graph)

Writes a graph to a Matrix Market file with custom options.

Functions

default_options()

@spec default_options() :: tuple()

Returns default Matrix Market serialization options.

options_with(weight_formatter, opts \\ [])

@spec options_with(
  (any() -> any()),
  keyword()
) :: tuple()

Creates Matrix Market options with custom configurations.

Raises ArgumentError if weight_formatter is not an arity-1 function or opts is invalid.

parse(input, g_type \\ nil)

@spec parse(String.t(), atom() | nil) ::
  {:ok, {:matrix_market_result, Yog.graph(), list()}} | {:error, term()}

Parses a Matrix Market string into a graph.

Raises ArgumentError if input is not a binary string or g_type is invalid.

Time complexity: $\mathcal{O}(V + E)$ where $V$ is node count and $E$ is edge count.

Parameters

  • input: Matrix Market format string
  • g_type: :directed or :undirected (overrides header symmetry if provided)

Returns

  • {:ok, {:matrix_market_result, graph, warnings}} on success
  • {:error, reason} on parsing failure

parse_with(input, g_type, node_parser, edge_parser)

@spec parse_with(String.t(), atom() | nil, (any() -> any()), (any() -> any())) ::
  {:ok, {:matrix_market_result, Yog.graph(), list()}} | {:error, term()}

Parses a Matrix Market string with custom node and edge parsers.

Raises ArgumentError if input is not a binary string or parsers/g_type are invalid.

Time complexity: $\mathcal{O}(V + E)$ where $V$ is node count and $E$ is edge count.

read(path, g_type \\ nil)

@spec read(String.t(), atom() | nil) ::
  {:ok, {:matrix_market_result, Yog.graph(), list()}} | {:error, term()}

Reads a graph from a Matrix Market file.

Raises ArgumentError if path is not a binary string.

read_with(path, g_type, node_parser, edge_parser)

@spec read_with(String.t(), atom() | nil, (any() -> any()), (any() -> any())) ::
  {:ok, {:matrix_market_result, Yog.graph(), list()}} | {:error, term()}

Reads a graph from a Matrix Market file with custom parsers.

Raises ArgumentError if path is not a binary string.

serialize(graph)

@spec serialize(Yog.graph()) :: String.t()

Serializes a graph to Matrix Market coordinate format.

Raises ArgumentError if graph is not a Yog.Graph or Yog.DAG struct.

Time complexity: $\mathcal{O}(V + E)$ where $V$ is node count and $E$ is edge count.

Example

iex> graph = Yog.directed()
...> |> Yog.add_node(1, nil)
...> |> Yog.add_node(2, nil)
...> |> Yog.add_edge_ensure(from: 1, to: 2, with: 1.5)
iex> mtx = Yog.IO.MatrixMarket.serialize(graph)
iex> String.contains?(mtx, "1 2 1.5")
true

serialize_with(options, graph)

@spec serialize_with(tuple(), Yog.graph()) :: String.t()

Serializes a graph to Matrix Market format with custom options.

Raises ArgumentError if options or graph are invalid.

Time complexity: $\mathcal{O}(V + E)$ where $V$ is node count and $E$ is edge count.

write(path, graph)

@spec write(String.t(), Yog.graph()) :: :ok | {:error, atom()}

Writes a graph to a Matrix Market file.

Raises ArgumentError if path is not a binary string or graph is invalid.

write_with(path, options, graph)

@spec write_with(String.t(), tuple(), Yog.graph()) :: :ok | {:error, atom()}

Writes a graph to a Matrix Market file with custom options.

Raises ArgumentError if path is not a binary string or options/graph are invalid.