Files
FemLite/tools/solvers/femlite_file_solver.py
T
2026-06-26 00:48:57 +08:00

379 lines
13 KiB
Python

#!/usr/bin/env python3
from __future__ import annotations
import argparse
import json
import math
import sys
from pathlib import Path
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(
description="Reference dense solver for FemLite file-exchange packages."
)
parser.add_argument("--manifest", required=True, help="FemLite handoff manifest")
parser.add_argument("--report", default="", help="Optional JSON report path")
parser.add_argument(
"--max-backward-error",
type=float,
default=1.0e-8,
help="Fail if backward error exceeds this value",
)
parser.add_argument(
"--matrix-source",
choices=("auto", "market", "csr"),
default="auto",
help="Read Matrix Market, CSR arrays, or prefer Matrix Market automatically",
)
parser.add_argument(
"--allow-singular",
action="store_true",
help="Write a report and return success for singular systems",
)
return parser.parse_args()
def read_manifest(path: Path) -> dict[str, str]:
lines = path.read_text(encoding="utf-8").splitlines()
if not lines or lines[0].strip() != "FEMLITE_EXTERNAL_HANDOFF_V1":
raise ValueError(f"{path} is not a FemLite external handoff manifest")
data: dict[str, str] = {"manifest": str(path)}
for line in lines[1:]:
stripped = line.strip()
if not stripped:
continue
parse_manifest_line(stripped, data)
data["base_dir"] = str(path.parent)
return data
def parse_manifest_line(line: str, data: dict[str, str]) -> None:
if line.startswith("nrow="):
for part in line.split(","):
key, value = part.split("=", 1)
data[key.strip()] = value.strip()
return
if line.startswith("class_id="):
for part in line.split(","):
key, value = part.split("=", 1)
data[key.strip()] = value.strip()
return
if "=" not in line:
raise ValueError(f"bad manifest line: {line}")
key, value = line.split("=", 1)
data[key.strip()] = value.strip()
def resolve_path(manifest: dict[str, str], key: str) -> Path:
if key not in manifest:
raise ValueError(f"manifest does not contain {key}")
path = Path(manifest[key])
if path.is_absolute():
return path
return Path(manifest["base_dir"]) / path
def read_vector(path: Path, expected_size: int | None = None) -> list[float]:
lines = path.read_text(encoding="utf-8").splitlines()
if len(lines) < 3 or lines[0].strip() != "FEMLITE_VECTOR_V1":
raise ValueError(f"{path} is not a FemLite vector file")
size_line = lines[2].strip()
if not size_line.startswith("size="):
raise ValueError(f"{path} vector size line is missing")
size = int(size_line.split("=", 1)[1])
if expected_size is not None and size != expected_size:
raise ValueError(f"{path} size {size} does not match {expected_size}")
values = [float(item.strip()) for item in lines[3:] if item.strip()]
if len(values) != size:
raise ValueError(f"{path} has {len(values)} values, expected {size}")
return values
def write_vector(path: Path, values: list[float], label: str) -> None:
lines = ["FEMLITE_VECTOR_V1", f"label={label}", f"size={len(values)}"]
lines.extend(f"{value:.16E}" for value in values)
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
def read_matrix_market(path: Path) -> list[list[float]]:
lines = path.read_text(encoding="utf-8").splitlines()
header = first_nonempty_line(lines)
parts = header.lower().split()
if len(parts) < 5 or parts[:4] != ["%%matrixmarket", "matrix", "coordinate", "real"]:
raise ValueError(f"{path} is not a real coordinate MatrixMarket file")
symmetry = parts[4]
shape_index = next_data_index(lines, 1)
nrow, ncol, entries = [int(item) for item in lines[shape_index].split()]
matrix = [[0.0 for _ in range(ncol)] for _ in range(nrow)]
for line in data_lines(lines[shape_index + 1 :]):
row, col, value = parse_market_entry(line)
matrix[row - 1][col - 1] += value
if symmetry == "symmetric" and row != col:
matrix[col - 1][row - 1] += value
actual = sum(1 for _ in data_lines(lines[shape_index + 1 :]))
if actual != entries:
raise ValueError(f"{path} declares {entries} entries but has {actual}")
return matrix
def read_csr_arrays(path: Path) -> list[list[float]]:
lines = path.read_text(encoding="utf-8").splitlines()
if len(lines) < 5 or lines[0].strip() != "FEMLITE_CSR_V1":
raise ValueError(f"{path} is not a FemLite CSR handoff file")
shape = parse_csr_shape(lines[1].strip())
nrow = shape["nrow"]
ncol = shape["ncol"]
nnz = shape["nnz"]
index_base = shape["index_base"]
row_start = require_label(lines, "row_ptr", 2) + 1
row_ptr = read_int_block(lines, row_start, nrow + 1, index_base)
col_start = require_label(lines, "col_ind", row_start + nrow + 1) + 1
col_ind = read_int_block(lines, col_start, nnz, index_base)
val_start = require_label(lines, "values", col_start + nnz) + 1
values = read_float_block(lines, val_start, nnz)
return dense_from_csr(nrow, ncol, row_ptr, col_ind, values)
def parse_csr_shape(line: str) -> dict[str, int]:
shape: dict[str, int] = {}
for part in line.split(","):
key, value = part.split("=", 1)
shape[key.strip()] = int(value.strip())
for key in ("nrow", "ncol", "nnz", "index_base"):
if key not in shape:
raise ValueError(f"CSR shape is missing {key}")
return shape
def require_label(lines: list[str], label: str, start: int) -> int:
if start >= len(lines) or lines[start].strip() != label:
raise ValueError(f"CSR file is missing {label} block")
return start
def read_int_block(
lines: list[str], start: int, count: int, index_base: int
) -> list[int]:
end = start + count
if end > len(lines):
raise ValueError("CSR integer block is truncated")
return [int(line.strip()) - index_base for line in lines[start:end]]
def read_float_block(lines: list[str], start: int, count: int) -> list[float]:
end = start + count
if end > len(lines):
raise ValueError("CSR value block is truncated")
return [float(line.strip()) for line in lines[start:end]]
def dense_from_csr(
nrow: int,
ncol: int,
row_ptr: list[int],
col_ind: list[int],
values: list[float],
) -> list[list[float]]:
if len(row_ptr) != nrow + 1:
raise ValueError("CSR row_ptr length mismatch")
matrix = [[0.0 for _ in range(ncol)] for _ in range(nrow)]
for row in range(nrow):
start = row_ptr[row]
end = row_ptr[row + 1]
if start < 0 or end < start or end > len(values):
raise ValueError("CSR row_ptr values are invalid")
for item in range(start, end):
col = col_ind[item]
if col < 0 or col >= ncol:
raise ValueError("CSR column index out of range")
matrix[row][col] += values[item]
return matrix
def first_nonempty_line(lines: list[str]) -> str:
for line in lines:
stripped = line.strip()
if stripped:
return stripped
raise ValueError("file is empty")
def next_data_index(lines: list[str], start: int) -> int:
for index in range(start, len(lines)):
stripped = lines[index].strip()
if stripped and not stripped.startswith("%"):
return index
raise ValueError("file ended before data line")
def data_lines(lines: list[str]) -> list[str]:
return [line.strip() for line in lines if line.strip() and not line.startswith("%")]
def parse_market_entry(line: str) -> tuple[int, int, float]:
parts = line.split()
if len(parts) != 3:
raise ValueError(f"bad MatrixMarket entry: {line}")
return int(parts[0]), int(parts[1]), float(parts[2])
def solve_dense(matrix: list[list[float]], rhs: list[float]) -> list[float]:
n = len(matrix)
if n == 0 or any(len(row) != n for row in matrix):
raise ValueError("dense solver requires a non-empty square matrix")
a = [row[:] + [rhs[i]] for i, row in enumerate(matrix)]
for pivot in range(n):
pivot_row = choose_pivot(a, pivot)
if abs(a[pivot_row][pivot]) <= 1.0e-14:
raise ZeroDivisionError(f"singular pivot at column {pivot + 1}")
if pivot_row != pivot:
a[pivot], a[pivot_row] = a[pivot_row], a[pivot]
eliminate_column(a, pivot)
return back_substitute(a)
def choose_pivot(a: list[list[float]], pivot: int) -> int:
best = pivot
best_value = abs(a[pivot][pivot])
for row in range(pivot + 1, len(a)):
value = abs(a[row][pivot])
if value > best_value:
best = row
best_value = value
return best
def eliminate_column(a: list[list[float]], pivot: int) -> None:
n = len(a)
for row in range(pivot + 1, n):
factor = a[row][pivot] / a[pivot][pivot]
if factor == 0.0:
continue
a[row][pivot] = 0.0
for col in range(pivot + 1, n + 1):
a[row][col] -= factor * a[pivot][col]
def back_substitute(a: list[list[float]]) -> list[float]:
n = len(a)
x = [0.0 for _ in range(n)]
for row in range(n - 1, -1, -1):
tail = sum(a[row][col] * x[col] for col in range(row + 1, n))
x[row] = (a[row][n] - tail) / a[row][row]
return x
def matvec(matrix: list[list[float]], x: list[float]) -> list[float]:
return [sum(value * x[col] for col, value in enumerate(row)) for row in matrix]
def vector_norm(values: list[float]) -> float:
return math.sqrt(sum(value * value for value in values))
def residual_metrics(
matrix: list[list[float]], rhs: list[float], solution: list[float]
) -> dict[str, float]:
ax = matvec(matrix, solution)
residual = [ax[i] - rhs[i] for i in range(len(rhs))]
residual_norm = vector_norm(residual)
rhs_norm = max(vector_norm(rhs), 1.0)
matrix_norm = max(matrix_inf_norm(matrix), 1.0)
x_norm = max(vector_norm(solution), 1.0)
backward = residual_norm / (matrix_norm * x_norm + rhs_norm)
return {
"residual_norm": residual_norm,
"relative_residual": residual_norm / rhs_norm,
"backward_error": backward,
}
def matrix_inf_norm(matrix: list[list[float]]) -> float:
if not matrix:
return 0.0
return max(sum(abs(value) for value in row) for row in matrix)
def write_report(path: Path, report: dict[str, object]) -> None:
path.write_text(json.dumps(report, indent=2, sort_keys=True) + "\n", encoding="utf-8")
def read_package_matrix(args: argparse.Namespace, manifest: dict[str, str]) -> tuple[list[list[float]], str]:
if args.matrix_source == "csr":
return read_csr_arrays(resolve_path(manifest, "csr")), "csr"
if args.matrix_source == "market":
return read_matrix_market(resolve_path(manifest, "matrix")), "market"
matrix_path = resolve_path(manifest, "matrix")
if matrix_path.exists():
return read_matrix_market(matrix_path), "market"
return read_csr_arrays(resolve_path(manifest, "csr")), "csr"
def solve_package(args: argparse.Namespace) -> int:
manifest_path = Path(args.manifest).resolve()
manifest = read_manifest(manifest_path)
nrow = int(manifest["nrow"])
ncol = int(manifest["ncol"])
matrix, matrix_source = read_package_matrix(args, manifest)
rhs = read_vector(resolve_path(manifest, "rhs"), nrow)
if nrow != ncol:
raise ValueError("reference dense solver requires a square matrix")
solution = solve_dense(matrix, rhs)
metrics = residual_metrics(matrix, rhs, solution)
write_vector(resolve_path(manifest, "solution"), solution, "solution")
report = build_report(manifest, solution, metrics, "solved")
report["matrix_source"] = matrix_source
maybe_write_report(args, manifest_path, report)
if metrics["backward_error"] > args.max_backward_error:
raise RuntimeError("backward error exceeds requested tolerance")
return 0
def build_report(
manifest: dict[str, str],
solution: list[float],
metrics: dict[str, float],
status: str,
) -> dict[str, object]:
return {
"status": status,
"backend": manifest.get("backend", ""),
"nrow": int(manifest.get("nrow", "0")),
"ncol": int(manifest.get("ncol", "0")),
"nnz": int(manifest.get("nnz", "0")),
"solution_size": len(solution),
"residual_norm": metrics.get("residual_norm", 0.0),
"relative_residual": metrics.get("relative_residual", 0.0),
"backward_error": metrics.get("backward_error", 0.0),
}
def maybe_write_report(
args: argparse.Namespace, manifest_path: Path, report: dict[str, object]
) -> None:
if args.report:
report_path = Path(args.report)
else:
report_path = manifest_path.with_name(manifest_path.stem.replace("_manifest", "") + "_solver_report.json")
write_report(report_path, report)
def main() -> int:
args = parse_args()
try:
return solve_package(args)
except ZeroDivisionError as exc:
if args.allow_singular:
print(str(exc), file=sys.stderr)
return 0
print(f"femlite_file_solver: {exc}", file=sys.stderr)
return 2
except Exception as exc:
print(f"femlite_file_solver: {exc}", file=sys.stderr)
return 1
if __name__ == "__main__":
raise SystemExit(main())