diff --git a/docs/src/manual/1-start.md b/docs/src/manual/1-start.md index 7f774a1..8f5a93d 100644 --- a/docs/src/manual/1-start.md +++ b/docs/src/manual/1-start.md @@ -2,29 +2,7 @@ ## Introduction -This manual aims to explain the fundamental concepts behind loading, manipulating and analyzing models with QUBOTools. - -## Quick Start Guide - -```@example quick-start -using QUBOTools - -path = joinpath(@__DIR__, "data", "problem.json") -``` - -### Reading a Model - -```@example quick-start -model = QUBOTools.read_model(path) -``` - -### Visualization - -```@example quick-start -using Plots - -plot(QUBOTools.ModelDensityPlot(model)) -``` +This manual aims to explain the fundamental concepts behind loading, manipulating and analyzing models with [QUBOTools](https://github.com/psrenergy/QUBOTools.jl). ## Table of Contents diff --git a/docs/src/manual/3-usage.md b/docs/src/manual/3-usage.md index 3bb3414..e351df8 100644 --- a/docs/src/manual/3-usage.md +++ b/docs/src/manual/3-usage.md @@ -6,9 +6,9 @@ using QUBOTools By loading the package with the `using` statement, only a few constants will be dumped in the namespace, most of them model types. -## Basic File I/O +## File I/O -To read and write QUBO models one is expected to use the `Base.read`/`Base.write` API. +To read and write models one should use the [`QUBOTools.read_model`](@ref)/[`QUBOTools.write_model`](@ref) API. ```@example manual # File Path @@ -20,6 +20,7 @@ model = QUBOTools.read_model(path) !!! info The [`QUBOTools.read_model`](@ref) and [`QUBOTools.write_model`](@ref) methods will try to infer the file format from the file extension. The format can be manually set by passing an extra optional parameter after the source path. + For more information, see [File Formats](@ref). ## Data Access @@ -35,6 +36,12 @@ QUBOTools.linear_terms(model) |> collect QUBOTools.quadratic_terms(model) |> collect ``` +### Model Analysis + +```@example manual +QUBOTools.density(model) +``` + ## File formats ### Conversion between formats diff --git a/docs/src/manual/5-formats.md b/docs/src/manual/5-formats.md index e0e36e0..7448df8 100644 --- a/docs/src/manual/5-formats.md +++ b/docs/src/manual/5-formats.md @@ -1,4 +1,4 @@ -# Formats +# File Formats | Format | Read | Write | Model | Solutions | Start | Metadata | | :------------------------------: | :---: | :---: | :---: | :-------: | :---: | :------: | @@ -9,7 +9,7 @@ ## Defining a Custom File Format -```@example file-format +```@example custom-file-format using QUBOTools struct SuperFormat <: QUBOTools.AbstractFormat @@ -18,3 +18,57 @@ struct SuperFormat <: QUBOTools.AbstractFormat SuperFormat(super::Bool = true) = new(super) end ``` + +### Writing Models + +To write a model using `SuperFormat`, one must implement the + +```julia +QUBOTools.write_model(io::IO, ::QUBOTools.AbstractModel{V,T,U}, ::SuperFormat) where {V,T,U} +``` + +method for the custom format. + +!!! info + This assumption is valid for text-based and binary formats. + If you pretend to write in a format that does not rely on `io::IO` (such as [`QUBOTools.QUBin`](@ref)), + you should also implement + + ```julia + QUBOTools.write_model(filepath::AbstractString, ::QUBOTools.AbstractModel{V,T,U}, ::SuperFormat) where {V,T,U} + ``` + +```@example custom-file-format +function QUBOTools.write_model(io::IO, model::QUBOTools.AbstractModel, fmt::SuperFormat) + if fmt.super + println(io, "Format Type: SUPER") + + _write_super_model(io, model) + else + println(io, "Format Type: Regular") + + _write_regular_model(io, model) + end + + return nothing +end +``` + +### Reading Models + +```@example custom-file-format +function QUBOTools.read_model(io::IO, fmt::SuperFormat) + header = readline(io) + + if fmt.super + @assert("SUPER" in header, "Invalid header: '$header' is not SUPER!") + + return _read_super_model(io) + else + return _read_regular_model(io) + end +end +``` + +!!! info + [`QUBOTools.read_model`](@ref) should return a [`QUBOTools.Model`](@ref) instance.