Add structured SampleSet export/import

docs/src/api.md

@@ -118,6 +118,7 @@ QUBOTools.hassample
 QUBOTools.AbstractSolution
 QUBOTools.SampleSet
 QUBOTools.solution
+QUBOTools.sampleset_table
 ```
 
 ```@docs
@@ -176,6 +177,8 @@ QUBOTools.write_model
 ```@docs
 QUBOTools.read_solution
 QUBOTools.write_solution
+QUBOTools.read_samples
+QUBOTools.write_samples
 ```
 
 ### Format & I/O Errors

docs/src/manual/6-solutions.md

@@ -12,6 +12,37 @@ Samples should be sorted by increasing values of ``\lambda``, then by decreasing
 
 Optimization results and metadata are stored in a specialized data structre, the [`QUBOTools.SampleSet`](@ref).
 
+## Tabular distribution caches
+
+Solver-independent sample distributions can be exported as CSV files with [`QUBOTools.write_samples`](@ref) and loaded again with [`QUBOTools.read_samples`](@ref). The CSV schema is stable and includes the sample rank, state, reads, value, and probability by default. Solution metadata, frame information, and package versions are stored as embedded JSON metadata, or in a JSON sidecar when `metadata_path` is provided.
+
+```julia
+solution = QUBOTools.solution(model)
+
+QUBOTools.write_samples("distribution.csv", solution)
+
+cached_solution = QUBOTools.read_samples("distribution.csv")
+rows = QUBOTools.sampleset_table(cached_solution)
+
+states = getproperty.(rows, :state)
+probabilities = getproperty.(rows, :probability)
+```
+
+When model context is available, passing the model records model scale, offset, and variable names in the metadata sidecar or embedded metadata:
+
+```julia
+QUBOTools.write_samples(
+    "distribution.csv",
+    model;
+    metadata_path = "distribution.metadata.json",
+)
+
+cached_solution = QUBOTools.read_samples(
+    "distribution.csv";
+    metadata_path = "distribution.metadata.json",
+)
+```
+
 ## Metadata
 
 The solution metadata should be stored in a JSON-compatible associative map with string keys, such as `Dict{String,Any}`.

src/QUBOTools.jl

@@ -57,6 +57,7 @@ export ↓, ↑, 𝔹, 𝕊
 
 # Exports: Solution Interface
 export Sample, SampleSet
+export read_samples, sampleset_table, write_samples
 
 # Interface definitions
 include("interface/form.jl")
@@ -90,6 +91,7 @@ include("library/solution/abstract.jl")
 include("library/solution/state.jl")
 include("library/solution/sample.jl")
 include("library/solution/sampleset.jl")
+include("library/solution/table.jl")
 
 include("library/model/abstract.jl")
 include("library/model/variable_map.jl")