Merge pull request #969 from JuliaOpt/od/mof

Add MathOptFormat.jl as FileFormats submodule

Author: odow

.gitignore

@@ -1,7 +1,8 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
+.vscode/*
 docs/build/
 docs/site/
-Manifest.toml
 test/Benchmarks/*.json
+Manifest.toml

LICENSE.md

@@ -2,22 +2,22 @@ The MathOptInterface.jl package is licensed under the MIT "Expat" License:
 
 > Copyright (c) 2017: Miles Lubin and contributors
 > Copyright (c) 2017: Google Inc.
-> 
+>
 > Permission is hereby granted, free of charge, to any person obtaining a copy
 > of this software and associated documentation files (the "Software"), to deal
 > in the Software without restriction, including without limitation the rights
 > to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 > copies of the Software, and to permit persons to whom the Software is
 > furnished to do so, subject to the following conditions:
-> 
+>
 > The above copyright notice and this permission notice shall be included in all
 > copies or substantial portions of the Software.
-> 
+>
 > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 > IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 > FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 > AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 > LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 > OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 > SOFTWARE.
-> 
+>

Project.toml

@@ -4,6 +4,10 @@ version = "0.9.8"
 
 [deps]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+CodecBzip2 = "523fee87-0ab8-5b00-afb7-3ecf72e48cfd"
+CodecZlib = "944b1d66-785c-5afd-91f1-9de20f533193"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+JSONSchema = "7d188eb4-7ad8-530c-ae41-71a32a6d4692"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MutableArithmetics = "d8a4904e-b15c-11e9-3269-09a3773c0cb0"
 OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
@@ -13,6 +17,10 @@ Unicode = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
 
 [compat]
 BenchmarkTools = "0.4"
+CodecBzip2 = "~0.6"
+CodecZlib = "~0.6"
+JSON = "~0.21"
+JSONSchema = "0.2"
 MutableArithmetics = "0.2"
 OrderedCollections = "1"
 julia = "1"

docs/Project.toml

@@ -3,4 +3,4 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
 
 [compat]
-Documenter = "~0.22"
+Documenter = "0.24"

docs/src/apimanual.md

@@ -792,6 +792,63 @@ becomes ``A = [3.0, 4.0]^\top`` as follows:
 modify(m, c, MultirowChange(x, [3.0, 4.0]))
 ```
 
+## File formats
+
+The `FileFormats` module provides functionality for reading and writing MOI models using
+[`write_to_file`](@ref) and [`read_from_file`](@ref).
+
+To write a model `src` to a MathOptFormat file, use:
+```julia
+src = # ...
+dest = FileFormats.Model(format = FileFormats.FORMAT_MOF)
+MOI.copy_to(dest, src)
+MOI.write_to_file(dest, "file.mof.json")
+```
+The list of supported formats is given by the [`FileFormats.FileFormat`](@ref) enum.
+
+Instead of the `format` keyword, you can also use the `filename` keyword argument to
+[`FileFormats.Model`](@ref). This will attempt to automatically guess the format from the
+file extension. For example:
+```julia
+src = # ...
+filename = "my_model.cbf.gz"
+dest = FileFormats.Model(filename = filename)
+MOI.copy_to(dest, src)
+MOI.write_to_file(dest, filename)
+
+src_2 = FileFormats.Model(filename = filename)
+MOI.read_from_file(src_2, filename)
+```
+Note how the compression format (GZip) is also automatically detected from the filename.
+
+In some cases `src` may contain constraints that are not supported by the file format (e.g.,
+the CBF format supports integer variables but not binary). If so, you should copy `src` to a
+bridged model using [`Bridges.full_bridge_optimizer`](@ref):
+```julia
+src = # ... conic model ...
+dest = FileFormats.Model(format = FileFormats.FORMAT_CBF)
+bridged = MOI.Bridges.full_bridge_optimizer(dest, Float64)
+MOI.copy_to(bridged, src)
+MOI.write_to_file(dest, "my_model.cbf")
+```
+You should also note that even after bridging, it may still not be possible to write the
+model to file because of unsupported constraints (e.g., PSD variables in the LP file
+format).
+
+In addition to [`write_to_file`](@ref) and [`read_from_file`](@ref), you can read and write
+directly from `IO` streams using `Base.write` and `Base.read!`:
+```julia
+src = # ...
+io = IOBuffer()
+dest = FileFormats.Model(format = FileFormats.FORMAT_MPS)
+MOI.copy_to(dest, src)
+write(io, dest)
+
+seekstart(io)
+src_2 = FileFormats.Model(format = FileFormats.FORMAT_MPS)
+read!(io, src_2)
+```
+
 ## Advanced
 
 ### Duals

docs/src/apireference.md

@@ -1018,3 +1018,13 @@ Benchmarks.suite
 Benchmarks.create_baseline
 Benchmarks.compare_against_baseline
 ```
+
+## File Formats
+
+Functions to help read and write MOI models to/from various file formats. See
+[File Formats](@ref) for more details.
+
+```@docs
+FileFormats.Model
+FileFormats.FileFormat
+```