diff --git a/doc/api.rst b/doc/api.rst index f817d866..d4c8ca95 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -18,6 +18,7 @@ Creating a model model.Model.add_variables model.Model.add_constraints model.Model.add_objective + model.Model.add_sos_constraints model.Model.add_piecewise_formulation piecewise.PiecewiseFormulation piecewise.Slopes @@ -26,10 +27,26 @@ Creating a model piecewise.tangent_lines model.Model.linexpr model.Model.remove_constraints + model.Model.reformulate_sos_constraints + model.Model.compute_infeasibilities + model.Model.format_infeasibilities model.Model.copy -Classes under the hook +Top-level helpers +================= + +.. autosummary:: + :toctree: generated/ + + align + merge + options + EvolvingAPIWarning + PerformanceWarning + + +Classes under the hood ====================== Variable @@ -46,7 +63,11 @@ Variable variables.Variable.sum variables.Variable.where variables.Variable.sanitize - variables.Variables + variables.Variable.to_linexpr + variables.Variable.fix + variables.Variable.unfix + variables.Variable.relax + variables.Variable.unrelax variables.ScalarVariable Variables @@ -61,7 +82,6 @@ Variables variables.Variables.add variables.Variables.remove variables.Variables.continuous - variables.Variables.integers variables.Variables.binaries variables.Variables.integers variables.Variables.flat @@ -82,6 +102,24 @@ LinearExpressions expressions.merge expressions.ScalarLinearExpression + +QuadraticExpressions +-------------------- + +.. autosummary:: + :toctree: generated/ + + expressions.QuadraticExpression + + +Objective +--------- + +.. autosummary:: + :toctree: generated/ + + objective.Objective + Constraint ---------- @@ -167,13 +205,27 @@ Solvers :toctree: generated/ solvers.CBC + solvers.COPT solvers.Cplex solvers.GLPK solvers.Gurobi solvers.Highs + solvers.Knitro + solvers.MindOpt solvers.Mosek + solvers.PIPS solvers.SCIP solvers.Xpress + solvers.cuPDLPx + + +Remote solving +============== + +.. autosummary:: + :toctree: generated/ + + remote.RemoteHandler Solving diff --git a/doc/benchmark.rst b/doc/benchmark.rst index da2a98e9..db9ec407 100644 --- a/doc/benchmark.rst +++ b/doc/benchmark.rst @@ -13,9 +13,9 @@ for large problems. The following figure shows the memory usage and speed for so .. math:: - & \min \;\; \sum_{i,j} 2 x_{i,j} \; y_{i,j} \\ + & \min \;\; \sum_{i,j} 2 x_{i,j} + y_{i,j} \\ s.t. & \\ - & x_{i,j} - y_{i,j} \; \ge \; i \qquad \forall \; i,j \in \{1,...,N\} \\ + & x_{i,j} - y_{i,j} \; \ge \; i-1 \qquad \forall \; i,j \in \{1,...,N\} \\ & x_{i,j} + y_{i,j} \; \ge \; 0 \qquad \forall \; i,j \in \{1,...,N\} diff --git a/doc/conf.py b/doc/conf.py index 5525d366..54a3ffab 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -18,7 +18,7 @@ # -- Project information ----------------------------------------------------- project = "linopy" -copyright = "2021, Fabian Hofmann" +copyright = "2021-2026, Fabian Hofmann" author = "Fabian Hofmann" # The full version, including alpha/beta/rc tags diff --git a/doc/contributing.rst b/doc/contributing.rst index 120683cb..4bb9b60a 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -13,14 +13,13 @@ You are invited to submit pull requests / issues to our Development Setup ================= -For linting, formatting and checking your code contributions -against our guidelines (e.g. we use `Black `_ as code style -and use `pre-commit `_: +For linting and formatting, we use `ruff `_ +and run it via `pre-commit `_: 1. Installation ``conda install -c conda-forge pre-commit`` or ``pip install pre-commit`` 2. Usage: * To automatically activate ``pre-commit`` on every ``git commit``: Run ``pre-commit install`` - * To manually run it: ``pre-commit run --all`` + * To manually run it: ``pre-commit run --all-files`` Running Tests ============= @@ -122,23 +121,25 @@ Then for every notebook: e.g. `Edit -> Clear all output` in JupyterLab. 3. Provide a link to the documentation: - Include a file ``foo.nblink`` located in ``doc/examples/foo.nblink`` + Include a file ``foo.nblink`` located in ``doc/foo.nblink`` with this content - .. code-block: - { - 'path' : '../../examples/foo.ipynb' - } + .. code-block:: json + + { + "path": "../examples/foo.ipynb" + } + + Adjust the path for your file's name. + This ``nblink`` allows us to link your notebook into the documentation. - Adjust the path for your file's name. - This ``nblink`` allows us to link your notebook into the documentation. 4. Link your file in the documentation: Either - * Include your ``examples/foo.nblink`` directly into one of - the documentations toctrees; or - * Tell us where in the documentation you want your example to show up + * Include your ``foo.nblink`` directly into one of + the documentation's toctrees; or + * Tell us where in the documentation you want your example to show up 5. Commit your changes. If the precommit hook you installed above kicks in, confirm diff --git a/doc/coordinate-alignment.nblink b/doc/coordinate-alignment.nblink new file mode 100644 index 00000000..ef588b91 --- /dev/null +++ b/doc/coordinate-alignment.nblink @@ -0,0 +1,3 @@ +{ + "path": "../examples/coordinate-alignment.ipynb" +} diff --git a/doc/index.rst b/doc/index.rst index a4d34ce7..c8906b74 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -23,7 +23,7 @@ Main features `xarray `__ which allows for many flexible data-handling features: -- Define (arrays of) contnuous or binary variables with +- Define (arrays of) continuous or binary variables with **coordinates**, e.g. time, consumers, etc. - Apply **arithmetic operations** on the variables like adding, subtracting, multiplying with all the **broadcasting** potentials of @@ -81,7 +81,7 @@ A BibTeX entry for LaTeX users is License ------- -Copyright 2021-2023 Fabian Hofmann +Copyright 2021-2026 Fabian Hofmann This package is published under MIT license. diff --git a/doc/prerequisites.rst b/doc/prerequisites.rst index 97d51296..afb0e8a7 100644 --- a/doc/prerequisites.rst +++ b/doc/prerequisites.rst @@ -36,21 +36,26 @@ CPU-based solvers - `Cbc `__ - open source, free, fast - `GLPK `__ - open source, free, not very fast - `HiGHS `__ - open source, free, fast +- `SCIP `__ - open source (Apache-2.0), fast MIP solver - `Gurobi `__ - closed source, commercial, very fast - `Xpress `__ - closed source, commercial, very fast (GPU acceleration available in v9.8+) - `Cplex `__ - closed source, commercial, very fast -- `MOSEK `__ -- `MindOpt `__ - +- `MOSEK `__ - closed source, commercial, strong on conic/QP +- `MindOpt `__ - closed source, commercial - `COPT `__ - closed source, commercial, very fast -For a subset of the solvers, Linopy provides a wrapper. +The ``linopy[solvers]`` extra installs the Python clients for the +supported solvers (HiGHS, SCIP, Gurobi, CPLEX, MOSEK, MindOpt, COPT, +Xpress, Knitro). For the commercial ones a separate license is still +required: .. code:: bash pip install linopy[solvers] -We recommend to install the HiGHS solver if possible, which is free and open source but not yet available on all platforms. +We recommend installing the HiGHS solver, which is free, open source, and +fast across a wide range of problem sizes: .. code:: bash diff --git a/examples/create-a-model-with-coordinates.ipynb b/examples/create-a-model-with-coordinates.ipynb index f2b12eed..e84c21b9 100644 --- a/examples/create-a-model-with-coordinates.ipynb +++ b/examples/create-a-model-with-coordinates.ipynb @@ -150,7 +150,7 @@ "metadata": {}, "outputs": [], "source": [ - "m.solve(solver_name=\"highs\")" + "m.solve(solver_name=\"highs\", output_flag=False)" ] }, { diff --git a/examples/create-a-model.ipynb b/examples/create-a-model.ipynb index a158e0cf..b6fc9705 100644 --- a/examples/create-a-model.ipynb +++ b/examples/create-a-model.ipynb @@ -215,7 +215,7 @@ "metadata": {}, "outputs": [], "source": [ - "m.solve(solver_name=\"highs\")" + "m.solve(solver_name=\"highs\", output_flag=False)" ] }, { diff --git a/examples/manipulating-models.ipynb b/examples/manipulating-models.ipynb index 81106ab3..6903386b 100644 --- a/examples/manipulating-models.ipynb +++ b/examples/manipulating-models.ipynb @@ -48,9 +48,9 @@ "con2 = m.add_constraints(5 * x + 2 * y >= 3 * factor, name=\"con2\")\n", "\n", "m.add_objective(x + 2 * y)\n", - "m.solve(solver_name=\"highs\")\n", + "m.solve(solver_name=\"highs\", output_flag=False)\n", "\n", - "m.solve(solver_name=\"highs\")\n", + "m.solve(solver_name=\"highs\", output_flag=False)\n", "sol = m.solution.to_dataframe()\n", "sol.plot(grid=True, ylabel=\"Optimal Value\")" ] @@ -95,7 +95,7 @@ "metadata": {}, "outputs": [], "source": [ - "m.solve(solver_name=\"highs\")\n", + "m.solve(solver_name=\"highs\", output_flag=False)\n", "sol = m.solution.to_dataframe()\n", "sol.plot(grid=True, ylabel=\"Optimal Value\")" ] @@ -137,7 +137,7 @@ "metadata": {}, "outputs": [], "source": [ - "m.solve(solver_name=\"highs\")\n", + "m.solve(solver_name=\"highs\", output_flag=False)\n", "sol = m.solution.to_dataframe()\n", "sol.plot(grid=True, ylabel=\"Optimal Value\")" ] @@ -190,7 +190,7 @@ "metadata": {}, "outputs": [], "source": [ - "m.solve(solver_name=\"highs\")\n", + "m.solve(solver_name=\"highs\", output_flag=False)\n", "sol = m.solution.to_dataframe()\n", "sol.plot(grid=True, ylabel=\"Optimal Value\")" ] @@ -242,7 +242,7 @@ "metadata": {}, "outputs": [], "source": [ - "m.solve(solver_name=\"highs\")\n", + "m.solve(solver_name=\"highs\", output_flag=False)\n", "sol = m.solution.to_dataframe()\n", "sol.plot(grid=True, ylabel=\"Optimal Value\")" ] @@ -276,7 +276,7 @@ "metadata": {}, "outputs": [], "source": [ - "m.solve(solver_name=\"highs\")\n", + "m.solve(solver_name=\"highs\", output_flag=False)\n", "sol = m.solution.to_dataframe()\n", "sol.plot(grid=True, ylabel=\"Optimal Value\")" ] @@ -326,7 +326,7 @@ "# Penalize activation of z in the objective\n", "m.objective = x + 3 * y + 10 * z\n", "\n", - "m.solve(solver_name=\"highs\")" + "m.solve(solver_name=\"highs\", output_flag=False)" ] }, { @@ -346,7 +346,7 @@ "source": [ "m.variables.binaries.fix()\n", "m.variables.binaries.relax()\n", - "m.solve(solver_name=\"highs\")\n", + "m.solve(solver_name=\"highs\", output_flag=False)\n", "\n", "# Dual values are now available on the constraints\n", "m.constraints[\"con1\"].dual" diff --git a/examples/transport-tutorial.ipynb b/examples/transport-tutorial.ipynb index b42e67e8..cd5cdccd 100644 --- a/examples/transport-tutorial.ipynb +++ b/examples/transport-tutorial.ipynb @@ -417,7 +417,7 @@ "outputs": [], "source": [ "# Solve the model\n", - "m.solve(solver_name=\"highs\")" + "m.solve(solver_name=\"highs\", output_flag=False)" ] }, {