From bbcb7a8cc8c417dd73afb60e2eb30205a07330d2 Mon Sep 17 00:00:00 2001 From: Corentin Le Molgat Date: Wed, 2 Jul 2025 11:55:25 +0200 Subject: [PATCH] update README.md --- ortools/graph/README.md | 109 +++++++++++++++++----------------------- ortools/pdlp/README.md | 6 --- 2 files changed, 47 insertions(+), 68 deletions(-) diff --git a/ortools/graph/README.md b/ortools/graph/README.md index 4831200355..7a070bed18 100644 --- a/ortools/graph/README.md +++ b/ortools/graph/README.md @@ -5,76 +5,64 @@ flow problems. It contains in particular: -* well-tuned algorithms (for example, shortest paths and - [Hamiltonian paths](https://en.wikipedia.org/wiki/Hamiltonian_path)). -* hard-to-find algorithms (Hamiltonian paths, push-relabel flow algorithms). -* other, more common algorithms, that are useful to use with graphs from - `util/graph`. +* well-tuned algorithms (for example, shortest paths and + [Hamiltonian paths](https://en.wikipedia.org/wiki/Hamiltonian_path)). +* hard-to-find algorithms (Hamiltonian paths, push-relabel flow algorithms). +* other, more common algorithms, that are useful to use with graphs from + `util/graph`. Generic algorithms for shortest paths: -* [`bounded_dijkstra.h`][bounded_dijkstra_h]: entry point for shortest paths. - This is the preferred implementation for most needs. - -* [`bidirectional_dijkstra.h`][bidirectional_dijkstra_h]: for large graphs, - this implementation might be faster than `bounded_dijkstra.h`. - -* [`shortest_paths.h`][shortest_paths_h]: shortest paths that are computed in - parallel (only if there are several sources). Includes - [Dijkstra](https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm) and - [Bellman-Ford](https://en.wikipedia.org/wiki/Bellman%E2%80%93Ford_algorithm) - algorithms. *Although its name is very generic, only use this implementation - if parallelism makes sense.* +* [`bounded_dijkstra.h`][bounded_dijkstra_h]: entry point for shortest paths. + This is the preferred implementation for most needs. +* [`bidirectional_dijkstra.h`][bidirectional_dijkstra_h]: for large graphs, + this implementation might be faster than `bounded_dijkstra.h`. +* [`shortest_paths.h`][shortest_paths_h]: shortest paths that are computed in + parallel (only if there are several sources). Includes + [Dijkstra](https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm) and + [Bellman-Ford](https://en.wikipedia.org/wiki/Bellman%E2%80%93Ford_algorithm) + algorithms. *Although its name is very generic, only use this implementation + if parallelism makes sense.* Specific algorithms for paths: -* [`dag_shortest_path.h`][dag_shortest_path_h]: shortest paths on directed - acyclic graphs. If you have such a graph, this implementation is likely to - be the fastest. Unlike most implementations, these algorithms have two - interfaces: a "simple" one (list of edges and weights) and a standard one - (taking as input a graph data structure from - [`//ortools/graph/graph.h`][graph_h]). - -* [`dag_constrained_shortest_path.`][dag_constrained_shortest_path_h]: - shortest paths on directed acyclic graphs with resource constraints. - -* [`hamiltonian_path.h`][hamiltonian_path_h]: entry point for computing - minimum [Hamiltonian paths](https://en.wikipedia.org/wiki/Hamiltonian_path) - and cycles on directed graphs with costs on arcs, using a - dynamic-programming algorithm. - -* [`eulerian_path.h`][eulerian_path_h]: entry point for computing minimum - [Eulerian paths](https://en.wikipedia.org/wiki/Eulerian_path) and cycles on - undirected graphs. +* [`dag_shortest_path.h`][dag_shortest_path_h]: shortest paths on directed + acyclic graphs. If you have such a graph, this implementation is likely to be + the fastest. Unlike most implementations, these algorithms have two interfaces + : a "simple" one (list of edges and weights) and a standard one (taking as + input a graph data structure from [`//ortools/graph/graph.h`][graph_h]). +* [`dag_constrained_shortest_path.`][dag_constrained_shortest_path_h]: shortest + paths on directed acyclic graphs with resource constraints. +* [`hamiltonian_path.h`][hamiltonian_path_h]: entry point for computing minimum + [Hamiltonian paths](https://en.wikipedia.org/wiki/Hamiltonian_path) and cycles + on directed graphs with costs on arcs, using a dynamic-programming algorithm. +* [`eulerian_path.h`][eulerian_path_h]: entry point for computing minimum + [Eulerian paths](https://en.wikipedia.org/wiki/Eulerian_path) and cycles on + undirected graphs. Graph decompositions: * [`connected_components.h`][connected_components_h]: entry point for computing connected components in an undirected graph. (It does not need an explicit graph class.) - * [`strongly_connected_components.h`][strongly_connected_components_h]: entry point for computing the strongly connected components of a directed graph. - -* [`cliques.h`][cliques_h]: entry point for computing maximum cliques and - clique covers in a directed graph, based on the Bron-Kerbosch algorithm.(It - does not need an explicit graph class.) +* [`cliques.h`][cliques_h]: entry point for computing maximum cliques and clique + covers in a directed graph, based on the Bron-Kerbosch algorithm.(It does not + need an explicit graph class.) Flow algorithms: -* [`linear_assignment.h`][linear_assignment_h]: entry point for solving linear - sum assignment problems (classical assignment problems where the total cost - is the sum of the costs of each arc used) on directed graphs with arc costs, - based on the Goldberg-Kennedy push-relabel algorithm. - -* [`max_flow.h`][max_flow_h]: entry point for computing maximum flows on - directed graphs with arc capacities, based on the Goldberg-Tarjan - push-relabel algorithm. - -* [`min_cost_flow.h`][min_cost_flow_h]: entry point for computing minimum-cost - flows on directed graphs with arc capacities, arc costs, and - supplies/demands at nodes, based on the Goldberg-Tarjan push-relabel - algorithm. +* [`linear_assignment.h`][linear_assignment_h]: entry point for solving linear + sum assignment problems (classical assignment problems where the total cost is + the sum of the costs of each arc used) on directed graphs with arc costs, + based on the Goldberg-Kennedy push-relabel algorithm. +* [`max_flow.h`][max_flow_h]: entry point for computing maximum flows on + directed graphs with arc capacities, based on the Goldberg-Tarjan push-relabel + algorithm. +* [`min_cost_flow.h`][min_cost_flow_h]: entry point for computing minimum-cost + flows on directed graphs with arc capacities, arc costs, and supplies/demands + at nodes, based on the Goldberg-Tarjan push-relabel algorithm. ## Class design @@ -201,21 +189,18 @@ node. ## Wrappers -* [`python`](python): the SWIG code that makes the wrapper available in Python - and its unit tests. - -* [`java`](java): the SWIG code that makes the wrapper available in Java and - its unit tests. - -* [`csharp`](csharp): the SWIG code that makes the wrapper available in C# and - its unit tests. +* [`python`](python): This directory contains the `pybind11` bindings to make + these C++ libraries available in Python. +* [`java`](java): the SWIG code that makes the wrapper available in Java and its + unit tests. +* [`csharp`](csharp): the SWIG code that makes the wrapper available in C# and + its unit tests. ## Samples You can find some canonical examples in [`samples`][samples]. - [graph_h]: ../graph/graph.h [bounded_dijkstra_h]: ../graph/bounded_dijkstra.h [bidirectional_dijkstra_h]: ../graph/bidirectional_dijkstra.h diff --git a/ortools/pdlp/README.md b/ortools/pdlp/README.md index b770f265a3..6a0245f557 100644 --- a/ortools/pdlp/README.md +++ b/ortools/pdlp/README.md @@ -12,21 +12,16 @@ performance and numerical stability. * [`primal_dual_hybrid_gradient.h`][primal_dual_hybrid_gradient_h]: The main entry point for the solver, which takes a `QuadraticProgram` and solver parameters. - * [`quadratic_program.h`][quadratic_program_h]: Defines the `QuadraticProgram` struct to represent the optimization problem, including objective vectors, constraint matrices, and bounds. - * [`quadratic_program_io.h`][quadratic_program_io_h]: Provides utilities to read quadratic programs from various file formats, including MPS and MPModelProto. - * [`sharded_quadratic_program.h`][sharded_quadratic_program_h] and [`sharder.h`][sharder_h]: These provide the infrastructure for sharding problem data and performing parallel computations. - * [`scheduler.h`][scheduler_h]: A thread scheduling interface that supports multiple backends (e.g. Eigen's thread pools). - * [`iteration_stats.h`][iteration_stats_h] and [`termination.h`][termination_h]: Contain logic for computing convergence and infeasibility statistics and checking termination criteria. @@ -46,7 +41,6 @@ performance and numerical stability. * [`samples/`](samples): This directory provides example usage of the library. - [primal_dual_hybrid_gradient_h]: ../pdlp/primal_dual_hybrid_gradient.h [quadratic_program_h]: ../pdlp/quadratic_program.h [quadratic_program_io_h]: ../pdlp/quadratic_program_io.h