From 9575343b248dc607541c03ff01cfb887a1ada8e1 Mon Sep 17 00:00:00 2001 From: Ricardo Fabbri Date: Mon, 8 Jul 2024 16:29:02 -0300 Subject: [PATCH] more readme --- tutorial/README.md | 70 +++++++++++++++++++++++++++++----------------- 1 file changed, 45 insertions(+), 25 deletions(-) diff --git a/tutorial/README.md b/tutorial/README.md index 54076da..786cb1f 100644 --- a/tutorial/README.md +++ b/tutorial/README.md @@ -5,16 +5,21 @@ ranging from an initial Macaulay prototype, to a more advanced Macaulay prototype to a fast C++ version. From the initial prototype to the final C++ code, there are a number of intermediate steps to follow. -## Running the example Macaulay2 template +In this tutorial ywe use a toy example codenamed `linecircle` which you can use +as a template for your own solver. You should codename your own +problem/formulation into a string, say, `problem1`, and follow what is done for +linecircle to your own problem. + +## Running the example Macaulay template The example is called linecircle and computes the intersection of a line and a circle. The equations are stored in: `equations-linecircle.m2` -### Solve the start solutions +### Solve the start solutions in Macaulay -In a terminal, type: +In a terminal, start Macaulay2, typing: ```bash m2 ``` @@ -35,39 +40,54 @@ It will write out the following files into the current folder: - `HxHt.cxx`, `HxH.cxx`: C++ evaluators for writing your optimized solver later on -## Solving your own system +### Solver for any target system in Macaulay -Give your new problem a name, say `problem1` +In file `end-linecircle.m2` variable `p1` will hold the desired target parameters. +For real problems, p1 will be constructed from problem data, say, image +correspondences. +In Macaulay, type: +``` +load("end-linecircle.m2") +``` -### Type your equations +The solutions will be output to the screen. -Copy the template over: +For chicago trifocal problem, these solutions take about 1min to compute. +This Macaulay solver will run a generic C++ homotopy continuation code under the +hood. This solver is code-matched to Minus fast C++ solver, with the +continuation parameters in Minus the same as the ones in Macaulay2, with some +additional parameters in Minus for performance. -``` -cp equations-linecircle.m2 equations-problem1.m2 -``` +## Optimizing the example Macaulay template -Edit the file typing your variables, parameters and equations, foloowing the -template as an example. +Inside the files `*-linecircle.m2` there are commented sections "Pro" after each +Macaulay command detaling what can be done to optimize the code. Try to +uncommment some of these and experiment with your code +## Building a fast C++ solver -### Compute start stystems +The Macaulay code can be used to generate a fast C++ solver. The `starSols`, +and `HxHt` and `HxH` files used in the `start-linecircle.m2` can be used to +write a fast solver within the Minus C++ framework. After the necessary steps, +the final solver executables are available as `cmd/minus-linecircle` in the +binary folder. Since these steps are more involved, we refer to the next +sections. -First, copy over the solution template: -``` -load("start-linecircle.m2") -``` -In a terminal, type: -```bash -m2 -``` + -Then +## Solving your own system -``` -load("start-linecircle.m2") -``` +Give your new problem a name, say `problem1`, you should first +copy the corresponding files in `minus/tutorial/*linecircle` by substituting the +string `linecircle` to `problem1` in the filenames and their contents. +This will get you running the basic scripted solver in Macaulay. +You can then follow the steps to produce a more optiized solver still in +Macaulay as documented above for `linecircle`. +There are steps to now to generate your own C++ optimized solver within the +Minus C++ framework. We are in the process of releasing the precise steps. +An idea can be had in the toploevel `minus/README.md` file with accompanying +videos. The final steps will be released soon.