diff --git a/docs/src/JuMP_documentation.pdf b/docs/src/JuMP_documentation.pdf new file mode 100644 index 00000000000..68974f8ec88 Binary files /dev/null and b/docs/src/JuMP_documentation.pdf differ diff --git a/docs/src/UpdatedIndexforPDF.md b/docs/src/UpdatedIndexforPDF.md new file mode 100644 index 00000000000..8117bbae340 --- /dev/null +++ b/docs/src/UpdatedIndexforPDF.md @@ -0,0 +1,144 @@ +# Introduction + +\begin{figure}[h] + \centering + \includegraphics[width=0.5\textwidth]{assets/logo-with-text.pdf} + \caption{JuMP logo} +\end{figure} + +Welcome to the documentation for JuMP. + +!!! note +This documentation is also available in md format: [\underline{index.md}](https://github.com/jump-dev/JuMP.jl/blob/master/docs/src/index.md). + +## What is JuMP? + +[\underline{JuMP}](https://github.com/jump-dev/JuMP.jl) is a domain-specific modeling +language for [\underline{mathematical optimization}](https://en.wikipedia.org/wiki/Mathematical_optimization) +embedded in [Julia](https://julialang.org/). + +JuMP makes it easy to formulate and solve a range of problem classes, including +linear programs, integer programs, conic programs, semidefinite programs, and +constrained nonlinear programs. Here’s an example: + +```julia +julia> using JuMP, Ipopt + +julia> function solve_constrained_least_squares_regression(A::Matrix, b::Vector) + m, n = size(A) + model = Model(Ipopt.Optimizer) + set_silent(model) + @variable(model, x[1:n]) + @variable(model, residuals[1:m]) + @constraint(model, residuals == A * x - b) + @constraint(model, sum(x) == 1) + @objective(model, Min, sum(residuals.^2)) + optimize!(model) + return value.(x) + end +solve_constrained_least_squares_regression (generic function with 1 method) + +julia> A, b = rand(10, 3), rand(10); + +julia> x = solve_constrained_least_squares_regression(A, b) +3-element Vector{Float64}: + 0.4137624719002825 + 0.09707679853084578 + 0.48916072956887174 +``` + +!!! tip +If you aren't sure if you should use JuMP, read [\underline{Should you use JuMP?}](https://github.com/jump-dev/JuMP.jl/blob/master/docs/src/should_i_use.md). + +## Resources for getting started + +There are a few ways to get started with JuMP: + +- Read the [\underline{Installation Guide}](https://github.com/jump-dev/JuMP.jl/blob/master/docs/src/installation.md). +- Read the introductory tutorials [\underline{Getting started with Julia}](https://github.com/jump-dev/JuMP.jl/blob/master/docs/src/tutorials/getting_started/introduction.md) and + [\underline{Getting started with JuMP}](https://github.com/jump-dev/JuMP.jl/blob/master/docs/src/tutorials/getting_started/introduction.md). +- Browse some of our modeling tutorials, including classics such as + [The diet problem](@ref), or the [Maximum likelihood estimation](@ref) problem + using nonlinear programming. + +!!! tip +Need help? Join the [\underline{community forum}](https://jump.dev/forum) +to search for answers to commonly asked questions. + + Before asking a question, make sure to read the post [make it easier to help you] + (https://discourse.julialang.org/t/psa-make-it-easier-to-help-you/14757), + which contains a number of tips on how to ask a good question. + +## How the documentation is structured + +Having a high-level overview of how this documentation is structured will help +you know where to look for certain things. + +- **Tutorials** contain worked examples of solving problems with JuMP. Start + here if you are new to JuMP, or you have a particular problem class you want + to model. + +- The **Manual** contains short code-snippets that explain how to achieve + specific tasks in JuMP. Look here if you want to know how to achieve a + particular task, such as how to [Delete a variable](@ref delete_a_variable) or + how to [Modify an objective coefficient](@ref). + +- The **API Reference** contains a complete list of the functions you can use in + JuMP. Look here if you want to know how to use a particular function. + +- The **Background information** section contains background reading material to + provide context to JuMP. Look here if you want an understanding of what JuMP + is and why we created it, rather than how to use it. + +- The **Developer docs** section contains information for people contributing to + JuMP development or writing JuMP extensions. Don't worry about this section if + you are using JuMP to formulate and solve problems as a user. + +- The **MathOptInterface** section is a self-contained copy of the documentation + for MathOptInterface. Look here for functions and constants beginning with + `MOI.`, as well as for general information on how MathOptInterface works. + +## Citing JuMP + +If you find JuMP useful in your work, we kindly request that you cite the +following paper ([\underline{preprint}](https://arxiv.org/abs/2206.03866)): + +```bibtex +@article{Lubin2023, + author = {Miles Lubin and Oscar Dowson and Joaquim {Dias Garcia} and + Joey Huchette and Beno{\^i}t Legat and Juan Pablo Vielma}, + title = {{JuMP} 1.0: {R}ecent improvements to a modeling language + for mathematical optimization}, + journal = {Mathematical Programming Computation}, + year = {2023}, + doi = {10.1007/s12532-023-00239-3} +} +``` + +## NumFOCUS + +![NumFOCUS logo](assets/numfocus-logo.png) + +JuMP is a Sponsored Project of NumFOCUS, a 501(c)(3) nonprofit charity in the +United States. NumFOCUS provides JuMP with fiscal, legal, and administrative +support to help ensure the health and sustainability of the project. Visit +[\underline{numfocus.org}](https://numfocus.org) for more information. + +You can support JuMP by [\underline{donating}](https://numfocus.org/donate-to-jump). + +Donations to JuMP are managed by NumFOCUS. For donors in the United States, +your gift is tax-deductible to the extent provided by law. As with any donation, +you should consult with your tax adviser about your particular tax situation. + +JuMP's largest expense is the annual JuMP-dev workshop. Donations will help us +provide travel support for JuMP-dev attendees and take advantage of other +opportunities that arise to support JuMP development. + +## License + +JuMP is licensed under the [\underline{MPL-2.0 software license}](https://mozilla.org/MPL/2.0/). +Consult the [\underline{license}](https://github.com/jump-dev/JuMP.jl/blob/master/LICENSE.md) +and the [\underline{Mozilla FAQ}](https://www.mozilla.org/en-US/MPL/2.0/FAQ/) for more +information. In addition, JuMP is typically used in conjunction with solver +packages and extensions which have their own licences. Consult their package +repositories for the specific licenses that apply. diff --git a/docs/src/header.tex b/docs/src/header.tex new file mode 100644 index 00000000000..987a6d98ddd --- /dev/null +++ b/docs/src/header.tex @@ -0,0 +1,53 @@ +\usepackage{geometry} +\geometry{ + a4paper, % Use A4 paper size + left=2.5cm, % Left margin + right=2.5cm, % Right margin + top=2.5cm, % Top margin + bottom=2.5cm, % Bottom margin + headheight=15pt, % Space for headers + headsep=25pt, % Space between header and text +} + +\usepackage{listings} +\lstset{ + language=Julia, + basicstyle=\ttfamily\footnotesize, % Set the font style + keywordstyle=\color{blue}, % Keyword color + commentstyle=\color{green}, % Comment color + stringstyle=\color{red}, % String color + numbers=left, % Line numbers on the left + numberstyle=\tiny\color{gray}, % Style of line numbers + stepnumber=1, % Number every line + numbersep=10pt, % Distance of numbers from the code + backgroundcolor=\color{white}, % Background color + showspaces=false, % Show spaces + showstringspaces=false, % Show string spaces + frame=single, % Frame around the code + tabsize=2, % Tab size + breaklines=true, % Automatically break long lines + postbreak=\mbox{\textcolor{red}{$\hookrightarrow$}\space}, % Indicate line breaks + xleftmargin=15pt, % Left padding for code + xrightmargin=15pt, % Right padding for code + aboveskip=10pt, % Space above code block + belowskip=10pt, % Space below code block +} + +\usepackage{setspace} % For line spacing +\setstretch{1.2} % Set line spacing to 1.2 + +\usepackage{microtype} % For better justification and line breaking +\sloppy % Allows LaTeX to be more lenient with line breaks + +\usepackage{hyperref} % For hyperlinks +\hypersetup{ + colorlinks=true, % false: boxed links; true: colored links + linkcolor=blue, % color of internal links + citecolor=blue, % color of citations + urlcolor=blue, % color of external links + pdfborder={0 0 0}, % Remove borders + pdfborderstyle={/S/S/W 0.5} % Set border width +} + +% Underline links +\renewcommand{\url}[1]{\underline{\texttt{#1}}} % Underline URLs diff --git a/docs/src/index.md b/docs/src/index.md index e182bb4f879..6ff7f76b104 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -19,12 +19,13 @@ Welcome to the documentation for JuMP. !!! note - This documentation is also available in PDF format: [JuMP.pdf](JuMP.pdf). +This documentation is also available in PDF format: [JuMP.pdf](JuMP_documentation.pdf). ## What is JuMP? [JuMP](https://github.com/jump-dev/JuMP.jl) is a domain-specific modeling -language for [mathematical optimization](https://en.wikipedia.org/wiki/Mathematical_optimization) +language for [mathematical optimization] +(https://en.wikipedia.org/wiki/Mathematical_optimization) embedded in [Julia](https://julialang.org/). JuMP makes it easy to formulate and solve a range of problem classes, including @@ -58,24 +59,25 @@ julia> x = solve_constrained_least_squares_regression(A, b) ``` !!! tip - If you aren't sure if you should use JuMP, read [Should you use JuMP?](@ref). +If you aren't sure if you should use JuMP, read [Should you use JuMP?](@ref). ## Resources for getting started There are a few ways to get started with JuMP: -* Read the [Installation Guide](@ref). -* Read the introductory tutorials [Getting started with Julia](@ref) and +- Read the [Installation Guide](@ref). +- Read the introductory tutorials [Getting started with Julia](@ref) and [Getting started with JuMP](@ref). -* Browse some of our modeling tutorials, including classics such as +- Browse some of our modeling tutorials, including classics such as [The diet problem](@ref), or the [Maximum likelihood estimation](@ref) problem using nonlinear programming. !!! tip - Need help? Join the [community forum](https://jump.dev/forum) - to search for answers to commonly asked questions. +Need help? Join the [community forum](https://jump.dev/forum) +to search for answers to commonly asked questions. - Before asking a question, make sure to read the post [make it easier to help you](https://discourse.julialang.org/t/psa-make-it-easier-to-help-you/14757), + Before asking a question, make sure to read the post [make it easier to help you] + (https://discourse.julialang.org/t/psa-make-it-easier-to-help-you/14757), which contains a number of tips on how to ask a good question. ## How the documentation is structured @@ -83,27 +85,27 @@ There are a few ways to get started with JuMP: Having a high-level overview of how this documentation is structured will help you know where to look for certain things. -* **Tutorials** contain worked examples of solving problems with JuMP. Start +- **Tutorials** contain worked examples of solving problems with JuMP. Start here if you are new to JuMP, or you have a particular problem class you want to model. -* The **Manual** contains short code-snippets that explain how to achieve +- The **Manual** contains short code-snippets that explain how to achieve specific tasks in JuMP. Look here if you want to know how to achieve a particular task, such as how to [Delete a variable](@ref delete_a_variable) or how to [Modify an objective coefficient](@ref). -* The **API Reference** contains a complete list of the functions you can use in +- The **API Reference** contains a complete list of the functions you can use in JuMP. Look here if you want to know how to use a particular function. -* The **Background information** section contains background reading material to +- The **Background information** section contains background reading material to provide context to JuMP. Look here if you want an understanding of what JuMP is and why we created it, rather than how to use it. -* The **Developer docs** section contains information for people contributing to +- The **Developer docs** section contains information for people contributing to JuMP development or writing JuMP extensions. Don't worry about this section if you are using JuMP to formulate and solve problems as a user. -* The **MathOptInterface** section is a self-contained copy of the documentation +- The **MathOptInterface** section is a self-contained copy of the documentation for MathOptInterface. Look here for functions and constants beginning with `MOI.`, as well as for general information on how MathOptInterface works. @@ -114,7 +116,8 @@ following paper ([preprint](https://arxiv.org/abs/2206.03866)): ```bibtex @article{Lubin2023, - author = {Miles Lubin and Oscar Dowson and Joaquim {Dias Garcia} and Joey Huchette and Beno{\^i}t Legat and Juan Pablo Vielma}, + author = {Miles Lubin and Oscar Dowson and Joaquim {Dias Garcia} and + Joey Huchette and Beno{\^i}t Legat and Juan Pablo Vielma}, title = {{JuMP} 1.0: {R}ecent improvements to a modeling language for mathematical optimization}, journal = {Mathematical Programming Computation}, year = {2023},