[docs] mention use_nlp_block when reading nonlinear file formats (#3958)

Author: odow

docs/src/manual/models.md

@@ -344,6 +344,39 @@ A JuMP Model
     [`variable_by_name`](@ref) or [`constraint_by_name`](@ref) to access
     specific variables or constraints.
 
+### Nonlinear file formats
+
+To maintain backwards compatibility, nonlinear models in `.mof.json` and `.nl`
+files are parsed into a [`MOI.NLPBlock`](@ref). To parse as
+[`MOI.ScalarNonlinearFunction`](@ref), pass the keyword `use_nlp_block = false`:
+
+```jldoctest
+julia> model = Model();
+
+julia> @variable(model, x >= 0);
+
+julia> @objective(model, Min, log(x));
+
+julia> filename = joinpath(mktempdir(), "model.mof.json");
+
+julia> write_to_file(model, filename)
+
+julia> new_model = read_from_file(filename; use_nlp_block = false)
+A JuMP Model
+├ solver: none
+├ objective_sense: MIN_SENSE
+│ └ objective_function_type: NonlinearExpr
+├ num_variables: 1
+├ num_constraints: 1
+│ └ VariableRef in MOI.GreaterThan{Float64}: 1
+└ Names registered in the model: none
+
+julia> print(new_model)
+Min log(x)
+Subject to
+ x ≥ 0
+```
+
 ## Relax integrality
 
 Use [`relax_integrality`](@ref) to remove any integrality constraints from the

src/file_formats.jl

@@ -225,46 +225,52 @@ Return a JuMP model read from `filename` in the format `format`.
 
 See [`MOI.FileFormats.FileFormat`](@ref) for a list of supported formats.
 
-## Compression
-
-If the filename ends in `.gz`, the file will be uncompressed using GZip.
-
-If the filename ends in `.bz2`, the file will be uncompressed using BZip2.
-
 ## Keyword arguments
 
 Other `kwargs` are passed to the `Model` constructor of the chosen format.
 
 For details, see the docstring each file format's `Model` constructor. For
 example, [`MOI.FileFormats.MPS.Model`](@ref).
 
+## Nonlinear models
+
+To maintain backwards compatibility, nonlinear models in `.mof.json` and `.nl`
+files are parsed into a [`MOI.NLPBlock`](@ref). To parse as [`MOI.ScalarNonlinearFunction`](@ref),
+pass the keyword `use_nlp_block = false`.
+
+## Compression
+
+If the filename ends in `.gz`, the file will be uncompressed using GZip.
+
+If the filename ends in `.bz2`, the file will be uncompressed using BZip2.
+
 ## Example
 
 ```jldoctest
 julia> model = Model();
 
 julia> @variable(model, x >= 0);
 
-julia> @objective(model, Min, 2 * x + 1);
+julia> @objective(model, Min, log(x));
 
-julia> filename = joinpath(mktempdir(), "model.mps");
+julia> filename = joinpath(mktempdir(), "model.mof.json");
 
-julia> write_to_file(model, filename; generic_names = true)
+julia> write_to_file(model, filename)
 
-julia> new_model = read_from_file(filename)
+julia> new_model = read_from_file(filename; use_nlp_block = false)
 A JuMP Model
 ├ solver: none
 ├ objective_sense: MIN_SENSE
-│ └ objective_function_type: AffExpr
+│ └ objective_function_type: NonlinearExpr
 ├ num_variables: 1
 ├ num_constraints: 1
 │ └ VariableRef in MOI.GreaterThan{Float64}: 1
 └ Names registered in the model: none
 
 julia> print(new_model)
-Min 2 C1 + 1
+Min log(x)
 Subject to
- C1 ≥ 0
+ x ≥ 0
 ```
 """
 function read_from_file(
@@ -298,33 +304,44 @@ Other `kwargs` are passed to the `Model` constructor of the chosen format.
 For details, see the docstring each file format's `Model` constructor. For
 example, [`MOI.FileFormats.MPS.Model`](@ref).
 
+## Nonlinear models
+
+To maintain backwards compatibility, nonlinear models in `.mof.json` and `.nl`
+files are parsed into a [`MOI.NLPBlock`](@ref). To parse as [`MOI.ScalarNonlinearFunction`](@ref),
+pass the keyword `use_nlp_block = false`.
+
 ## Example
 
 ```jldoctest
 julia> model = Model();
 
 julia> @variable(model, x >= 0);
 
-julia> @objective(model, Min, 2 * x + 1);
+julia> @objective(model, Min, log(x));
 
 julia> io = IOBuffer();
 
-julia> write(io, model; format = MOI.FileFormats.FORMAT_MPS);
+julia> write(io, model; format = MOI.FileFormats.FORMAT_MOF);
 
 julia> seekstart(io);
 
-julia> new_model = read(io, Model; format = MOI.FileFormats.FORMAT_MPS)
+julia> new_model = read(
+           io,
+           Model;
+           format = MOI.FileFormats.FORMAT_MOF,
+           use_nlp_block = false,
+       )
 A JuMP Model
 ├ solver: none
 ├ objective_sense: MIN_SENSE
-│ └ objective_function_type: AffExpr
+│ └ objective_function_type: NonlinearExpr
 ├ num_variables: 1
 ├ num_constraints: 1
 │ └ VariableRef in MOI.GreaterThan{Float64}: 1
 └ Names registered in the model: none
 
 julia> print(new_model)
-Min 2 x + 1
+Min log(x)
 Subject to
  x ≥ 0
 ```