From a9f26adbf48b13d6794110c73049f424a753b34c Mon Sep 17 00:00:00 2001 From: David Eisenbud Date: Tue, 26 Sep 2023 09:30:57 -0700 Subject: [PATCH 01/73] Frank's changes in DGAlgebras --- M2/Macaulay2/packages/DGAlgebras.m2 | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/M2/Macaulay2/packages/DGAlgebras.m2 b/M2/Macaulay2/packages/DGAlgebras.m2 index b2b07e4e48b..a8a66982905 100644 --- a/M2/Macaulay2/packages/DGAlgebras.m2 +++ b/M2/Macaulay2/packages/DGAlgebras.m2 @@ -239,8 +239,12 @@ killCycles = method(TypicalValue=>DGAlgebra,Options => {StartDegree => 1, EndDeg killCycles DGAlgebra := opts -> A -> ( -- for now, this will only work for DG algebras with H_0(A) = k retVal := 0; - endDegree := 0; - if opts.EndDegree == -1 then endDegree = opts.StartDegree; + + endDegree := if opts.EndDegree == -1 then opts.StartDegree else opts.EndDegree; + if opts.StartDegree > endDegree then error "Starting degree is not less than or equal to ending degree."; + n := opts.StartDegree; + foundHomology := false; + if opts.StartDegree > endDegree then error "Starting degree is not less than or equal to ending degree."; n := opts.StartDegree; foundHomology := false; From 600376e717071baa20a3b3ae357aceb82eca7dc4 Mon Sep 17 00:00:00 2001 From: David Eisenbud Date: Tue, 4 Jun 2024 14:58:21 -0600 Subject: [PATCH 02/73] new AInfinity --- M2/Macaulay2/packages/AInfinity.m2 | 136 ++++++++++++++++++++++++++++- 1 file changed, 134 insertions(+), 2 deletions(-) diff --git a/M2/Macaulay2/packages/AInfinity.m2 b/M2/Macaulay2/packages/AInfinity.m2 index 9b533770817..9756505085e 100644 --- a/M2/Macaulay2/packages/AInfinity.m2 +++ b/M2/Macaulay2/packages/AInfinity.m2 @@ -19,6 +19,7 @@ export { "picture", "displayBlocks", "extractBlocks", + "mapComponents", --symbols "Check" } @@ -544,6 +545,61 @@ mapComponents(HashTable, HashTable, ZZ) := List =>(mA,mG,len) ->( ))))) ) +mapComponents1 = method() +mapComponents1(HashTable, HashTable, ZZ) := List =>(mA,mG,i) ->( + --The output is a list D_1..D_len + --where D_t is a list of the matrices of maps + --F_t ->comp(u,F_t) -> comp(v, F_(t-1) -> F_(t-1) + --where comp(u,F_t) is the component of F_t labeled u + --and similarly for v,F_(t-1). + --Thus sum D_t will be the map F.dd_t in the Burke resolution. + R := mA#"ring"; + S := ring presentation R; + B := mA#"resolution"; + M := mG#"module"; + G := mG#"resolution"; + F := burkeData(M,i+1); -- the list of labeled free modules + --Now form the components of the maps. + + for t from i to i+1 list ( + + --First construct vv, the list of valid maps F_t --> F_(t-1). + c :=componentsAndIndices F_t; + flatten apply(#c_0, s-> ( + u := c_1_s; + --now focus on the maps starting from the u component of F_t + numRComponents := #u-1; + vv0 := mapComponents u; -- not all the vv0_i are valid. + (C,K) := componentsAndIndices F_(t-1); + vv := select(vv0, v-> member(v_3,K)); + --for each member v of vv, the list v_3 is the index of a component + --of F_(t-1) to which the u component maps. + --The rest of v describes the map, as follows: + for v in vv list ( + sign := v_0; + p := v_1; + q := v_2; + v_0*map(F_(t-1), F_t, + (F_(t-1))_[u_{0..p-1}|{-1+sum u_{p..q}}|u_{q+1..numRComponents}]* + (if q (M,b) ->( golodBetti0(F,K,b) ) +totalBetti = method() +totalBetti(Module, ZZ) := ZZ => (M,i) ->( + R := ring M; + mA := aInfinity R; + mG := aInfinity(mA,M); +elapsedTime D := mapComponents1(mA, mG, i); + n := numcols D#0#0;-- nonminimal rank + S := ring D#0#0; + kS := map(coefficientRing S, S); +elapsedTime maps := D/sum/kS; +elapsedTime maps = maps/mutableMatrix; +elapsedTime ranks := maps/rank; + n-sum ranks + ) + beginDocumentation() /// restart @@ -1759,13 +1830,24 @@ isGolod(S/I), isHomologyAlgebraTrivial(H)) --------- restart -needsPackage "AInfinity" ---- +loadPackage "AInfinity" +peek loadedFiles +-- +mapComponents + S = ZZ/101[x_1..x_5] I = x_1*ideal(vars S) R = S/I +use R M = R^1/ideal(x_1..x_3) + + R = ring M; + mA = aInfinity R; + mG = aInfinity(mA,M); + D = mapComponents(mA,mG,3); +netList D + time F = burkeResolution(M, 8, Check =>false) time F = burkeResolution(M, 8, Check =>true) time res(M, LengthLimit => 8) -- 100 times faster! @@ -1790,3 +1872,53 @@ R = S/gor 3 elapsedTime burkeResolution(coker vars R, 7) elapsedTime res(coker vars R, LengthLimit => 7) picture burkeResolution(coker vars R, 5) +j + + +----------- +restart +debug needsPackage "AInfinity" + +-- + + + +S = ZZ/101[x_1..x_2] +I = (ideal vars S)^2 +R = S/I +use R +M = coker random(R^2, R^{3:-1}) + + +S = ZZ/101[x_1..x_3] +I = ideal random(S^1, S^{-2,-3,-4,-5,-6}); +R = S/I +M = coker random(R^1, R^{1:-4}) + +elapsedTime aR = aInfinity R; +elapsedTime aM = aInfinity (aR, M); +elapsedTime betti res (M, LengthLimit=>10) +elapsedTime totalBetti(M,10) +elapsedTime burkeResolution(M,11) + +mm = mapComponents1(aR, aM, 8); +numcols mm#0#0 +numcols mm#1#0 + R = ring M; +mA +mG + + D = mapComponents1(mA,mG,3) + D/sum +redu = map(ZZ/101,S) +D/sum/redu/rank +numrows first (D#1) +betti res M + +F = burkeResolution(M,3) +picture F +netList D +viewHelp AInfinity +prune HH F +options picture +transpose picture o25.dd_10 From dba08098377413527e9f93f5138c148cb741aed5 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Fri, 24 Apr 2026 16:41:05 -0400 Subject: [PATCH 03/73] Add documentation workflow scaffolding --- .github/ISSUE_TEMPLATE/documentation-task.yml | 92 +++++++ DocumentationPlan.md | 234 ++++++++++++++++++ README.md | 1 + 3 files changed, 327 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/documentation-task.yml create mode 100644 DocumentationPlan.md diff --git a/.github/ISSUE_TEMPLATE/documentation-task.yml b/.github/ISSUE_TEMPLATE/documentation-task.yml new file mode 100644 index 00000000000..916fe63a855 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation-task.yml @@ -0,0 +1,92 @@ +name: Documentation task +description: File a scoped issue for documentation changes in Macaulay2. +title: "docs: " +labels: + - docs +body: + - type: dropdown + id: area + attributes: + label: Documentation area + description: Choose the main area affected by this issue. + options: + - Build and install docs + - Internal/reference docs + - Package docs + - Tutorials and examples + - Editor/tooling docs + - Contributor guidance + - Repository-wide cleanup + - Other + validations: + required: true + + - type: textarea + id: summary + attributes: + label: Summary + description: State the problem in one short paragraph. + placeholder: What is wrong, unclear, outdated, or missing? + validations: + required: true + + - type: textarea + id: paths + attributes: + label: Affected paths + description: List the files or directories likely to change. + placeholder: | + README.md + M2/Macaulay2/docs/index.rst + M2/Macaulay2/packages/SomePackage/README.md + validations: + required: true + + - type: textarea + id: desired_outcome + attributes: + label: Desired outcome + description: Describe what "done" looks like for this task. + placeholder: After this issue is complete, what should a reader be able to do or understand? + validations: + required: true + + - type: textarea + id: verification + attributes: + label: Verification + description: Say how the updated docs should be checked. + placeholder: | + Example: + - Rerun the commands in the README + - Check links + - Build the relevant docs, if applicable + validations: + required: true + + - type: dropdown + id: size + attributes: + label: Estimated size + options: + - Small + - Medium + - Large + validations: + required: true + + - type: checkboxes + id: review_flags + attributes: + label: Review flags + options: + - label: This issue needs mathematical review. + - label: This issue needs examples or commands to be rerun. + - label: This issue may require follow-up issues instead of one PR. + + - type: textarea + id: dependencies + attributes: + label: Dependencies or blockers + description: Note related issues, required decisions, or blockers. + placeholder: Optional diff --git a/DocumentationPlan.md b/DocumentationPlan.md new file mode 100644 index 00000000000..11306ad71f5 --- /dev/null +++ b/DocumentationPlan.md @@ -0,0 +1,234 @@ +# Documentation Plan + +This file coordinates the documentation refresh work currently landing on +`doc-updates`. + +Use GitHub issues and a GitHub Project to track execution. Do not treat this +file as the day-to-day checklist for every edit. Its job is to define scope, +workflow, and the first backlog to turn into issues. + +## Goals + +1. Improve the accuracy of user-facing documentation. +2. Make documentation work easier to claim, review, and finish. +3. Standardize how documentation tasks are described and verified. +4. Keep pull requests small enough for mathematical and editorial review. + +## Working Model + +1. Create a GitHub Project named `M2 Documentation Refresh`. +2. Use columns `Backlog`, `Ready`, `In Progress`, `In Review`, and `Done`. +3. File one GitHub issue per documentation task. +4. Link each issue to the relevant paths, a clear owner, and a definition of + done. +5. Land focused pull requests into `doc-updates`, not one large omnibus PR. +6. Close the issue only after review and any needed follow-up verification. + +## Suggested Labels + +- `docs`: default label for documentation work. +- `docs-build`: install, build, packaging, or toolchain documentation. +- `docs-reference`: reference pages, generated docs, or API-style docs. +- `docs-package`: package-specific documentation. +- `docs-tutorial`: tutorials, examples, and teaching-oriented docs. +- `docs-editors`: editor integration and syntax-highlighting docs. +- `needs-math-review`: requires subject-matter review for correctness. +- `needs-example`: examples must be rerun or rewritten. +- `good-first-issue`: suitable for a new contributor. +- `blocked`: cannot proceed until another issue lands. + +## Definition Of Done + +A documentation issue is done when all of the following are true: + +1. The affected files and audience are identified in the issue. +2. The updated text is accurate for the current code or workflow. +3. Examples, commands, or screenshots were rerun when practical, or the PR + explicitly notes what could not be rerun. +4. Links and cross-references in the touched files were checked. +5. The PR description states how the change was verified. +6. The issue is linked to the PR and any follow-up work is split into new + issues instead of hidden in review comments. + +## Issue Size Guidance + +- Small: one file or one tightly scoped topic; target one review. +- Medium: one subsystem or one package doc surface; may span several files. +- Large: an audit or rewrite that should be split into smaller child issues. + +Default to small or medium issues. Large issues should usually be tracking +issues, not implementation issues. + +## Review Checklist + +When reviewing documentation PRs, check: + +1. Is the text correct for the current version of the code? +2. Is the intended audience clear? +3. Do the examples still run, or is any uncertainty called out? +4. Are links, package names, branch names, and paths still current? +5. Is the PR small enough to review without hidden scope? + +## Starter Backlog + +The items below are intended to become GitHub issues. Each one is small enough +to assign to a person or pair, and together they cover the main documentation +surfaces already present in this repository. + +### Coordination And Contributor Guidance + +1. Audit top-level contribution guidance. + Paths: `README.md`, `.github/pull_request_template.md` + Done when: contributor-facing instructions are current, critical workflow + notes live in the repo when possible, and stale references are removed or + flagged. + +2. Add a short documentation contributor guide. + Paths: `DocumentationPlan.md`, new guide if needed + Done when: contributors can tell where package docs, internal docs, and + README-style docs live, and how to claim work. + +3. Define documentation style conventions. + Paths: new guide or repo-local section linked from `DocumentationPlan.md` + Done when: reviewers have a shared standard for headings, code blocks, link + style, example formatting, and tone. + +4. Establish the documentation project board and label set on GitHub. + Paths: GitHub Project and repo labels + Done when: the board exists, labels are created, and at least the initial + backlog issues are loaded. + +### Build, Install, And Tooling Docs + +5. Audit the main build overview. + Paths: `M2/README.md`, `M2/BUILD/README.md` + Done when: supported workflows, prerequisite expectations, and entry points + are clear and non-duplicative. + +6. Review container and packaging documentation. + Paths: `M2/BUILD/docker/README.md`, `M2/BUILD/docker/*/README.md`, + `M2/BUILD/rpm/README.md` + Done when: the supported images and packaging flows are accurately described + and obsolete instructions are called out. + +7. Review editor integration documentation. + Paths: `M2/Macaulay2/editors/README.md`, + `M2/Macaulay2/editors/emacs/README.md`, + `M2/Macaulay2/editors/vim/README_linux`, + `M2/Macaulay2/editors/vim/README_macos`, + `M2/Macaulay2/editors/prism/README.md`, + `M2/Macaulay2/editors/pygments/README.md` + Done when: installation and usage instructions match the current editor + tooling and redundant text is reduced. + +8. Document how to verify documentation changes locally. + Paths: repo-local guide or existing README files + Done when: contributors know what to run for doc-adjacent checks and how to + report partial verification. + +### Internal And Generated Documentation + +9. Audit the internal documentation landing page. + Paths: `M2/Macaulay2/docs/index.rst`, `M2/Macaulay2/docs/modules.rst` + Done when: the landing page accurately describes what is generated, what is + hand-maintained, and where readers should start. + +10. Review Sphinx and Doxygen build assumptions. + Paths: `M2/Macaulay2/docs/CMakeLists.txt`, `M2/Macaulay2/docs/conf.py`, + `M2/Macaulay2/docs/Doxyfile.in` + Done when: build expectations are documented and mismatches between config + and prose are recorded or fixed. + +11. Inventory major gaps in internal docs coverage. + Paths: `M2/Macaulay2/docs/`, generated output as needed + Done when: missing modules, weak landing pages, and unclear navigation are + captured as follow-up issues instead of remaining implicit. + +### Package Documentation + +12. Audit the package documentation entry point. + Paths: `M2/Macaulay2/packages/README` + Done when: readers can understand how package docs are organized and how to + discover package-specific documentation. + +13. Review `NumericalAlgebraicGeometry` documentation. + Paths: `M2/Macaulay2/packages/NumericalAlgebraicGeometry/README`, + `M2/Macaulay2/packages/NumericalAlgebraicGeometry/TST/README.txt` + Done when: overview, prerequisites, and example/test references are current. + +14. Review `NumericalSchubertCalculus` documentation. + Paths: `M2/Macaulay2/packages/NumericalSchubertCalculus/README` and related + README files under that package + Done when: the overview and supporting README files still reflect the + current package layout and usage. + +15. Review `OldChainComplexes` documentation structure. + Paths: `M2/Macaulay2/packages/OldChainComplexes/docs/*.m2` + Done when: the landing points, narrative flow, and page naming are coherent + for a newcomer to the package docs. + +16. Review `MergeTeX` documentation. + Paths: `M2/Macaulay2/packages/MergeTeX/README.md` + Done when: setup and usage notes are accurate and concise. + +17. Review `TropicalToric` documentation. + Paths: `M2/Macaulay2/packages/TropicalToric/README.md` + Done when: the README accurately describes scope, entry points, and any + external assumptions. + +18. Review `MonodromySolver` example documentation. + Paths: `M2/Macaulay2/packages/MonodromySolver/paper-examples/README.md` + Done when: the example documentation clearly states what is reproducible and + what environment assumptions exist. + +19. Identify packages missing an overview or landing page. + Paths: `M2/Macaulay2/packages/` + Done when: missing-package-doc issues are filed as discrete follow-ups + instead of one vague umbrella task. + +### Tutorials, Examples, And Teaching Material + +20. Audit the Computations Book landing page. + Paths: `M2/Macaulay2/tests/ComputationsBook/README` + Done when: the top-level description, navigation, and reader expectations + are current. + +21. Review chapter-level Computations Book README files for stale terminology. + Paths: `M2/Macaulay2/tests/ComputationsBook/*/README` + Done when: terminology, chapter descriptions, and references are consistent + across the chapter folders. + +22. Verify a representative sample of tutorial examples. + Paths: selected files under `M2/Macaulay2/tests/ComputationsBook/` + Done when: issues are filed for broken, outdated, or confusing examples and + the verified sample is documented in the issue. + +### Repository-Wide Cleanup + +23. Run a broken-link sweep across Markdown and README files. + Paths: repo-wide Markdown and README files, excluding third-party submodules + Done when: broken internal links, moved files, and stale external links are + fixed or captured in follow-up issues. + +24. Standardize branch-name and workflow references in docs. + Paths: repo-wide documentation files + Done when: references to outdated branch names or outdated GitHub workflows + are corrected where appropriate. + +25. Identify documentation that belongs in the repo instead of only on the wiki. + Paths: top-level docs and places that link heavily to the wiki + Done when: critical contributor guidance has a repo-local home or a tracked + follow-up issue. + +26. Create a `good-first-issue` wave for new documentation contributors. + Paths: GitHub issues and labels + Done when: at least five narrowly scoped doc issues are labeled and ready to + assign. + +## Notes For Leads + +1. Keep the integration branch stable enough that people can branch from it + without inheriting unrelated work. +2. Prefer issues with exact paths over issues framed as "improve docs". +3. If a task changes both mathematical content and prose, ask for math review + explicitly instead of assuming an editorial review is enough. diff --git a/README.md b/README.md index 798fa431584..bbb943634f2 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ Contributions to the code of Macaulay2 are welcome. The source code is available via our GitHub [repository](https://github.com/Macaulay2/M2), where you can also report bugs via the [issue tracker](https://github.com/Macaulay2/M2/issues). For brief instructions, see [here](https://github.com/Macaulay2/M2/wiki/Git-for-Macaulay2-Contributors). +For the current documentation refresh workflow, see [DocumentationPlan.md](DocumentationPlan.md). To start working on an existing github "issue", volunteer to work on it, so you can get "assigned" to the issue, thereby preventing duplication of From 050e58fd2f6bd83cb3571d907ff32d07779a2b8c Mon Sep 17 00:00:00 2001 From: aalmousa Date: Sat, 25 Apr 2026 11:27:44 -0400 Subject: [PATCH 04/73] Update docs workflow guidance and labels --- .github/pull_request_template.md | 21 ++- DocumentationPlan.md | 265 +++++++++++++++++++++++++++++-- README.md | 17 +- 3 files changed, 281 insertions(+), 22 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3ad99033e21..10cfa689e99 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,5 +1,18 @@ - +Describe the documentation change and the main files it touches. + +## Related Issue + +Link the issue in `aalmousa/M2` that this PR addresses. + +## Verification + +List what you checked locally. Be explicit about examples, links, generated +html, or any verification you could not complete. + +## Notes + +- For the documentation refresh workflow in this fork, open PRs against + `doc-updates`, not `master`. +- Keep the scope focused. Split unrelated documentation work into separate PRs. diff --git a/DocumentationPlan.md b/DocumentationPlan.md index 11306ad71f5..274c35f982d 100644 --- a/DocumentationPlan.md +++ b/DocumentationPlan.md @@ -26,7 +26,7 @@ workflow, and the first backlog to turn into issues. ## Suggested Labels -- `docs`: default label for documentation work. +- `documentation`: default label for documentation work. - `docs-build`: install, build, packaging, or toolchain documentation. - `docs-reference`: reference pages, generated docs, or API-style docs. - `docs-package`: package-specific documentation. @@ -34,7 +34,7 @@ workflow, and the first backlog to turn into issues. - `docs-editors`: editor integration and syntax-highlighting docs. - `needs-math-review`: requires subject-matter review for correctness. - `needs-example`: examples must be rerun or rewritten. -- `good-first-issue`: suitable for a new contributor. +- `good first issue`: suitable for a new contributor. - `blocked`: cannot proceed until another issue lands. ## Definition Of Done @@ -151,76 +151,309 @@ surfaces already present in this repository. Done when: readers can understand how package docs are organized and how to discover package-specific documentation. -13. Review `NumericalAlgebraicGeometry` documentation. +13. Redesign the main Macaulay2 documentation landing page. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2` + Done when: the landing page is organized for mathematicians and other + users trying to find examples, tutorials, package docs, and topic-based + entry points, and the rendered html has been previewed locally. + +14. Surface buried high-value guides from the main documentation landing page. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/ov_language.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/ov_packages.m2`, + `M2/Macaulay2/packages/BeginningMacaulay2.m2` + Done when: the homepage or nearby top-level navigation makes it easier to + find `BeginningMacaulay2`, `debugging`, `the debugger`, `error handling`, + and practical package-usage guidance, and any new links have been checked + in rendered html. + +15. Remove or relocate the stale contributor list on the main documentation landing page. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2`, + related author or acknowledgement pages as needed + Done when: the hand-maintained documentation-contributor list no longer + clutters the homepage, and any remaining attribution is either accurate and + maintainable or moved to a more appropriate page. + +16. Review `NumericalAlgebraicGeometry` documentation. Paths: `M2/Macaulay2/packages/NumericalAlgebraicGeometry/README`, `M2/Macaulay2/packages/NumericalAlgebraicGeometry/TST/README.txt` Done when: overview, prerequisites, and example/test references are current. -14. Review `NumericalSchubertCalculus` documentation. +17. Review `NumericalSchubertCalculus` documentation. Paths: `M2/Macaulay2/packages/NumericalSchubertCalculus/README` and related README files under that package Done when: the overview and supporting README files still reflect the current package layout and usage. -15. Review `OldChainComplexes` documentation structure. +18. Review `OldChainComplexes` documentation structure. Paths: `M2/Macaulay2/packages/OldChainComplexes/docs/*.m2` Done when: the landing points, narrative flow, and page naming are coherent for a newcomer to the package docs. -16. Review `MergeTeX` documentation. +19. Review `MergeTeX` documentation. Paths: `M2/Macaulay2/packages/MergeTeX/README.md` Done when: setup and usage notes are accurate and concise. -17. Review `TropicalToric` documentation. +20. Review `TropicalToric` documentation. Paths: `M2/Macaulay2/packages/TropicalToric/README.md` Done when: the README accurately describes scope, entry points, and any external assumptions. -18. Review `MonodromySolver` example documentation. +21. Review `MonodromySolver` example documentation. Paths: `M2/Macaulay2/packages/MonodromySolver/paper-examples/README.md` Done when: the example documentation clearly states what is reproducible and what environment assumptions exist. -19. Identify packages missing an overview or landing page. +22. Identify packages missing an overview or landing page. Paths: `M2/Macaulay2/packages/` Done when: missing-package-doc issues are filed as discrete follow-ups instead of one vague umbrella task. +Audit summary from the first static distributed-package scan on `2026-04-25`: +the 294 distributed packages showed no broken relative links in their +README/Markdown files, 13 packages had almost no visible doc entry point, and +131 packages still had doc-surface `TODO` or `undocumented` markers that need +triage. + +23. Expand landing pages and entry-point docs for low-surface distributed packages. + Paths: `M2/Macaulay2/packages/Browse.m2`, + `M2/Macaulay2/packages/Benchmark.m2`, + `M2/Macaulay2/packages/Dmodules.m2`, + `M2/Macaulay2/packages/Schubert2.m2`, + `M2/Macaulay2/packages/Schubert2/doc.m2`, + `M2/Macaulay2/packages/RationalPoints.m2`, + `M2/Macaulay2/packages/BeginningMacaulay2.m2`, + `M2/Macaulay2/packages/Serialization.m2`, + `M2/Macaulay2/packages/Units.m2`, + `M2/Macaulay2/packages/RandomCurves.m2`, + `M2/Macaulay2/packages/VectorGraphics.m2`, + `M2/Macaulay2/packages/WhitneyStratifications.m2`, + `M2/Macaulay2/packages/Msolve.m2` + Done when: each package has a visible overview or landing page, and the + user-facing packages in this group have at least one clear example or + tutorial path. + +24. Finish algebra and geometry package docs that still contain explicit TODO or undocumented placeholders. + Paths: `M2/Macaulay2/packages/LocalRings.m2`, + `M2/Macaulay2/packages/LocalRings/doc.m2`, + `M2/Macaulay2/packages/LocalRings/examples.m2`, + `M2/Macaulay2/packages/Saturation.m2`, + `M2/Macaulay2/packages/Saturation/doc.m2`, + `M2/Macaulay2/packages/Saturation/quotient-doc.m2`, + `M2/Macaulay2/packages/Saturation/saturate-doc.m2`, + `M2/Macaulay2/packages/MinimalPrimes.m2`, + `M2/Macaulay2/packages/MinimalPrimes/doc.m2`, + `M2/Macaulay2/packages/PrimaryDecomposition/doc.m2`, + `M2/Macaulay2/packages/PrimaryDecomposition/examples.m2`, + `M2/Macaulay2/packages/IntegralClosure.m2`, + `M2/Macaulay2/packages/Triangulations.m2`, + `M2/Macaulay2/packages/Truncations.m2`, + `M2/Macaulay2/packages/Truncations/docs.m2`, + `M2/Macaulay2/packages/Varieties/*.m2` + Done when: the explicit `TODO` and `undocumented` placeholders in these + package doc surfaces are either resolved or split into smaller tracked + issues, and navigation problems such as the orphan `quotient` node in + `Saturation/quotient-doc.m2` are fixed or documented. + +25. Finish interface and application package docs that still contain explicit TODO or undocumented placeholders. + Paths: `M2/Macaulay2/packages/SCSCP/docs.m2`, + `M2/Macaulay2/packages/SCSCP/examples.m2`, + `M2/Macaulay2/packages/Python/doc.m2`, + `M2/Macaulay2/packages/Python/doc/tutorials.m2`, + `M2/Macaulay2/packages/ReactionNetworks.m2`, + `M2/Macaulay2/packages/ReactionNetworks/Readme.md`, + `M2/Macaulay2/packages/Cremona/documentation.m2`, + `M2/Macaulay2/packages/NumericalAlgebraicGeometry/doc.m2`, + `M2/Macaulay2/packages/NumericalSchubertCalculus/README`, + `M2/Macaulay2/packages/Bertini/doc.m2`, + `M2/Macaulay2/packages/BernsteinSato/DOC/*.m2`, + `M2/Macaulay2/packages/VectorGraphics.m2`, + `M2/Macaulay2/packages/WhitneyStratifications.m2`, + `M2/Macaulay2/packages/Msolve.m2` + Done when: undocumented exports or explicit `TODO` notes in these package + docs are reduced, external prerequisites are explained where needed, and + the package docs give a clear starting point for first-time users. + +26. Curate package example and tutorial surfaces that are present but unfinished or hard to navigate. + Paths: `M2/Macaulay2/packages/LocalRings/examples.m2`, + `M2/Macaulay2/packages/PrimaryDecomposition/examples.m2`, + `M2/Macaulay2/packages/BernsteinSato/DOC/*.m2`, + `M2/Macaulay2/packages/Bertini/TST/*.tst.m2`, + `M2/Macaulay2/packages/NumericalAlgebraicGeometry/README`, + `M2/Macaulay2/packages/NumericalAlgebraicGeometry/TST/README.txt`, + `M2/Macaulay2/packages/Python/doc/tutorials.m2`, + `M2/Macaulay2/packages/ReactionNetworks/example*.m2`, + `M2/Macaulay2/packages/SCSCP/examples.m2`, + `M2/Macaulay2/packages/OldChainComplexes/docs/*.m2` + Done when: the example entry points in this set are labeled clearly as + tutorials, demos, or tests, obviously unfinished sections are completed or + trimmed, and readers can tell which files are meant to be read first. + +27. Record the first full distributed-package documentation audit and keep it split into follow-up waves. + Paths: `M2/Macaulay2/packages/=distributed-packages`, + `DocumentationPlan.md` + Done when: the audit results remain summarized in the plan with counts, and + the high-priority packages from that scan are represented by explicit + follow-up items instead of one umbrella note. + ### Tutorials, Examples, And Teaching Material -20. Audit the Computations Book landing page. +28. Review `BeginningMacaulay2` as a first-user tutorial. + Paths: `M2/Macaulay2/packages/BeginningMacaulay2.m2`, + `M2/Macaulay2/packages/BeginningMacaulay2/tutorial` + Done when: the tutorial still works as a modern first stop for new users, + obvious stale workflow assumptions are corrected, and its role in the main + documentation navigation is clear. + +29. Refresh the commutative algebra tutorial set and its dated course framing. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/tu_elementary.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/loads.m2` + Done when: the `Fall 2005` / `Math 634` framing is either removed or + intentionally contextualized, tutorial titles and descriptions are clearer + for current users, and the exposed examples still make sense as entry + points. + +30. Refresh `Tutorial: Modules in Macaulay2`. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/tu_modules.m2` + Done when: stale references such as `Section XX` and speculative + future-behavior notes are removed or rewritten, and the tutorial still + reads coherently for users learning modules from examples. + +31. Refresh `Tutorial: Divisors`. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/tu_divisors.m2` + Done when: obsolete forward references such as the missing “next divisor + tutorial” and historical performance notes are removed or replaced, and the + stated scope matches current functionality. + +32. Audit the advanced geometry tutorials for clarity and dated assumptions. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/tu_canEmbed.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/tu_Fano.m2` + Done when: terminology, caveats, and example framing have been reviewed for + current readers, and any stale notes are split into follow-up issues or + fixed. + +33. Audit the Computations Book landing page. Paths: `M2/Macaulay2/tests/ComputationsBook/README` Done when: the top-level description, navigation, and reader expectations are current. -21. Review chapter-level Computations Book README files for stale terminology. +34. Review chapter-level Computations Book README files for stale terminology. Paths: `M2/Macaulay2/tests/ComputationsBook/*/README` Done when: terminology, chapter descriptions, and references are consistent across the chapter folders. -22. Verify a representative sample of tutorial examples. +35. Verify a representative sample of tutorial examples. Paths: selected files under `M2/Macaulay2/tests/ComputationsBook/` Done when: issues are filed for broken, outdated, or confusing examples and the verified sample is documented in the issue. +### Core Language And Reference Documentation + +36. Audit core overview links, placeholders, and navigation gaps. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/ov_getting_started.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/ov_documentation.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/ov_ringmaps.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/ov_groebner_bases.m2` + Done when: top-level `TO` and `SeeAlso` targets have been spot-checked, + placeholder or commented-out navigation such as missing troubleshooting or + contributor entry points is either resolved or split into tracked follow-up + work, and any broken or stale links found in these core overview pages are + fixed or recorded. + +37. Triage the core function docs that are still explicitly marked `status: TODO`. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/functions/*-doc.m2` + Done when: the current `status: TODO` set has been reviewed, the most + important exported functions are grouped into actionable follow-up issues, + and the backlog distinguishes between missing coverage, thin coverage, and + pages that mostly need examples. + +38. Document exported text, rendering, and serialization methods that are still marked undocumented. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/functions/expression-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/hypertext-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/html-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/mathML-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/tex-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/texMath-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/toString-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/toExternalString-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/format-doc.m2` + Done when: exported methods in this cluster no longer rely on generic + `undocumented` placeholders, and the docs explain what these routines are + for with at least one concrete example or cross-reference per page. + +39. Document exported filesystem, REPL, and utility functions that still have TODO or undocumented coverage. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/functions/isDirectory-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/isRegularFile-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/readDirectory-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/readlink-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/realpath-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/removeDirectory-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/findSynonyms-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/isGlobalSymbol-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/use-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/net-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/peek-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/index-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/clean-doc.m2` + Done when: the exported utilities in this group have enough explanation and + examples to be discoverable from the docs without reading source, and + obvious TODO markers or undocumented method placeholders are removed. + +40. Document exported algebra, Gröbner, and linear-algebra functions that still have TODO or undocumented coverage. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/gb-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/gbRemove-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/forceGB-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/rank-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/SVD-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/eigenvalues-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/eigenvectors-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/mingens-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/degrees-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/someTerms-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/monomials-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/GF-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/pseudoRemainder-doc.m2` + Done when: this cluster of exported mathematical functions has been triaged + into concrete documentation fixes with examples where needed, and clearly + missing or placeholder pages are no longer hidden behind `status: TODO`. + +41. Expand thin explanations and examples in the core getting-started, debugging, and module docs. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/ov_getting_started.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/generators-doc.m2`, + `M2/Macaulay2/packages/Macaulay2Doc/functions/preimage-doc.m2` + Done when: the docs add the missing explanatory context called out in the + source comments, stale “needs upgrades” notes are resolved, and example + gaps such as the missing `preimage` example or the unsalvaged + `generators` examples are addressed. + ### Repository-Wide Cleanup -23. Run a broken-link sweep across Markdown and README files. +42. Run a broken-link sweep across Markdown and README files. Paths: repo-wide Markdown and README files, excluding third-party submodules Done when: broken internal links, moved files, and stale external links are fixed or captured in follow-up issues. -24. Standardize branch-name and workflow references in docs. +43. Standardize branch-name and workflow references in docs. Paths: repo-wide documentation files Done when: references to outdated branch names or outdated GitHub workflows are corrected where appropriate. -25. Identify documentation that belongs in the repo instead of only on the wiki. +44. Identify documentation that belongs in the repo instead of only on the wiki. Paths: top-level docs and places that link heavily to the wiki Done when: critical contributor guidance has a repo-local home or a tracked follow-up issue. -26. Create a `good-first-issue` wave for new documentation contributors. +45. Create a `good-first-issue` wave for new documentation contributors. Paths: GitHub issues and labels Done when: at least five narrowly scoped doc issues are labeled and ready to assign. diff --git a/README.md b/README.md index bbb943634f2..c70f11a7ee1 100644 --- a/README.md +++ b/README.md @@ -20,8 +20,21 @@ See `CITATION.cff` for information about citing Macaulay2. Contributions to the code of Macaulay2 are welcome. The source code is available via our GitHub [repository](https://github.com/Macaulay2/M2), where you can also report bugs via the [issue tracker](https://github.com/Macaulay2/M2/issues). -For brief instructions, see [here](https://github.com/Macaulay2/M2/wiki/Git-for-Macaulay2-Contributors). -For the current documentation refresh workflow, see [DocumentationPlan.md](DocumentationPlan.md). +For general background on the upstream git workflow, see the +[Git for Macaulay2 Contributors](https://github.com/Macaulay2/M2/wiki/Git-for-Macaulay2-Contributors) +wiki page. + +For the documentation refresh workflow on this fork: + +* Track work in the `aalmousa/M2` issues and the `M2 Documentation Refresh` + project. +* Branch from `doc-updates`. +* Open pull requests against `aalmousa/M2:doc-updates`, not `master`. +* State what you verified locally, especially for examples, links, and + regenerated documentation pages. + +See [DocumentationPlan.md](DocumentationPlan.md) for the current documentation +workflow, issue taxonomy, and local preview guidance. To start working on an existing github "issue", volunteer to work on it, so you can get "assigned" to the issue, thereby preventing duplication of From fdc74f63d7437d195014ded2d94c83b69676661d Mon Sep 17 00:00:00 2001 From: aalmousa Date: Sat, 25 Apr 2026 12:03:30 -0400 Subject: [PATCH 05/73] Add documentation contributor guides --- .github/ISSUE_TEMPLATE/documentation-task.yml | 2 +- .github/pull_request_template.md | 2 + DocumentationGuide.md | 113 ++++++++++++++++++ DocumentationPlan.md | 3 + DocumentationStyleGuide.md | 94 +++++++++++++++ README.md | 6 +- 6 files changed, 217 insertions(+), 3 deletions(-) create mode 100644 DocumentationGuide.md create mode 100644 DocumentationStyleGuide.md diff --git a/.github/ISSUE_TEMPLATE/documentation-task.yml b/.github/ISSUE_TEMPLATE/documentation-task.yml index 916fe63a855..64735a31530 100644 --- a/.github/ISSUE_TEMPLATE/documentation-task.yml +++ b/.github/ISSUE_TEMPLATE/documentation-task.yml @@ -2,7 +2,7 @@ name: Documentation task description: File a scoped issue for documentation changes in Macaulay2. title: "docs: " labels: - - docs + - documentation body: - type: dropdown id: area diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 10cfa689e99..55d6fb32eb1 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -16,3 +16,5 @@ html, or any verification you could not complete. - For the documentation refresh workflow in this fork, open PRs against `doc-updates`, not `master`. - Keep the scope focused. Split unrelated documentation work into separate PRs. +- See `DocumentationGuide.md` and `DocumentationStyleGuide.md` for the current + workflow and documentation standards. diff --git a/DocumentationGuide.md b/DocumentationGuide.md new file mode 100644 index 00000000000..cb906700163 --- /dev/null +++ b/DocumentationGuide.md @@ -0,0 +1,113 @@ +# Documentation Guide + +This guide is for contributors working on the documentation refresh in +`aalmousa/M2`. Use it together with [DocumentationPlan.md](DocumentationPlan.md) +and [DocumentationStyleGuide.md](DocumentationStyleGuide.md). + +## Scope + +The main documentation surfaces in this repository are: + +- Core and user-facing docs: `M2/Macaulay2/packages/Macaulay2Doc/` +- Package docs: `M2/Macaulay2/packages//` and package `.m2` files +- Internal docs: `M2/Macaulay2/docs/` +- Repo-level docs: `README.md`, `M2/BUILD/`, `M2/Macaulay2/editors/`, and + related README files + +Edit source documentation, not generated html. + +## Workflow + +1. Claim or create an issue in `aalmousa/M2` and track it in the + `M2 Documentation Refresh` project. +2. Branch from `doc-updates`. +3. Keep the PR focused on one issue or one child issue. +4. Open pull requests against `aalmousa/M2:doc-updates`, not `master`. +5. If the scope grows, split follow-up work into new issues instead of widening + the PR. + +## Before Editing + +- Identify the audience first: end user, package user, contributor, or internal + maintainer. +- Find the source page that actually generates the docs you want to change. +- Prefer improving an existing landing page or tutorial path over creating a + second entry point for the same material. +- Check whether the issue should carry `needs-math-review` or `needs-example`. + +## Local Preview + +Assume `$M2BUILDDIR` points to an existing build tree. For most documentation +changes, rebuild only the package you touched. + +For prose, navigation, or landing-page edits that do not change example code: + +```sh +make -C "$M2BUILDDIR/Macaulay2/packages" \ + PACKAGES=Macaulay2Doc \ + RemakePackages=false \ + RemakeAllDocumentation=false \ + CheckDocumentation=false \ + IARGS='RunExamples => false' +``` + +Replace `Macaulay2Doc` with the package you edited. The regenerated html usually +appears under: + +```text +$M2BUILDDIR/usr-dist/common/share/doc/Macaulay2//html/ +``` + +If you changed examples or expected output, use the normal package rebuild: + +```sh +make -C "$M2BUILDDIR/Macaulay2/packages" \ + PACKAGES=YourPackage \ + RemakePackages=false \ + RemakeAllDocumentation=false +``` + +For package docs, also use `viewHelp` or `installPackage` when that is the +quickest way to confirm the rendered result. + +Reserve the expensive flags for final verification: + +- `RunExamples => false`: fastest preview for text-only edits +- default example behavior: normal path for example changes +- `RerunExamples=true`: rerun all examples for one package +- `RemakeAllDocumentation=true`: full package-doc rebuild +- `CheckDocumentation=true`: stronger completeness check + +If there is a pre-existing build failure, say exactly what page or command you +were still able to verify. + +## Verification + +Every documentation PR should say what was checked locally. Use this checklist: + +- the affected page renders or `viewHelp` shows the expected change +- links, `SeeAlso`, `Subnodes`, and top-level navigation were checked +- examples were rerun when practical, or the PR says why they were not +- any external prerequisite or setup instructions were checked against current + reality + +## Labels And Review + +Use the repo labels to keep work triageable: + +- `documentation`: default label for documentation work +- `docs-build`, `docs-reference`, `docs-package`, `docs-tutorial`, + `docs-editors`: documentation area labels +- `needs-math-review`: use when correctness depends on mathematical review +- `needs-example`: use when examples or outputs should be rerun +- `blocked`: use when another issue must land first + +## Definition Of Done + +A documentation change is ready when: + +1. The audience and affected files are clear. +2. The text is accurate for the current code or workflow. +3. Links and cross-references were checked. +4. Examples were rerun when practical, or the limitation is stated plainly. +5. The PR explains verification and links the relevant issue. diff --git a/DocumentationPlan.md b/DocumentationPlan.md index 274c35f982d..b19622333a7 100644 --- a/DocumentationPlan.md +++ b/DocumentationPlan.md @@ -24,6 +24,9 @@ workflow, and the first backlog to turn into issues. 5. Land focused pull requests into `doc-updates`, not one large omnibus PR. 6. Close the issue only after review and any needed follow-up verification. +Contributor-facing guidance lives in [DocumentationGuide.md](DocumentationGuide.md) +and [DocumentationStyleGuide.md](DocumentationStyleGuide.md). + ## Suggested Labels - `documentation`: default label for documentation work. diff --git a/DocumentationStyleGuide.md b/DocumentationStyleGuide.md new file mode 100644 index 00000000000..b564a6ba0eb --- /dev/null +++ b/DocumentationStyleGuide.md @@ -0,0 +1,94 @@ +# Documentation Style Guide + +This guide sets the documentation standards for the refresh on `doc-updates`. +It is intentionally short and operational. + +## Priorities + +1. Optimize for a mathematically literate user trying to accomplish something. +2. Make the next step obvious. +3. Keep examples trustworthy. + +## General Rules + +- Write for the page's audience, not for someone already reading the source. +- Prefer direct present-tense statements over historical notes or speculation. +- Do not leave `TODO`, `FIXME`, `Section XX`, or references to missing follow-up + tutorials in user-facing pages. +- Avoid stale course framing, version-era notes, or performance caveats unless + they are still relevant. +- If a symbol or page is important enough to export, it should normally be + documented rather than left behind `undocumented`. + +## Page Types + +### Function And Method Pages + +When the doc surface supports it, include: + +- `Headline` +- `Usage` +- `Inputs` +- `Outputs` +- a short explanation of behavior and context +- at least one example or a strong cross-reference +- `SeeAlso` + +If an option materially changes behavior, document the option node too. + +### Package Landing Pages + +A package landing page should answer these questions quickly: + +- What does the package do? +- What package needs to be loaded? +- Are there external prerequisites? +- Where should a new user start? +- Where are the main examples or tutorials? + +### Tutorials + +- State the goal of the tutorial early. +- Say what packages need to be loaded. +- Present examples in an order a reader can follow. +- Separate tutorial guidance from raw test material. +- If a tutorial assumes external software, say so near the top. + +### Internal Or Generated Docs + +- Say whether the page is hand-maintained or generated. +- Point readers toward the right source file or build context. +- Do not pretend an internal page is a user-facing landing page. + +## Examples + +- Prefer one minimal example and one slightly richer example over a long dump. +- Examples should be runnable when practical. +- If output is expensive, unstable, or externally dependent, say so explicitly. +- Do not leave an example block in place if it has become misleading. + +## Navigation And Cross-References + +- Every new page should be reachable from at least one parent page. +- `SeeAlso`, `Subnodes`, and top-level navigation should point somewhere useful. +- Avoid orphan pages and commented-out navigation. +- Surface high-value guides from landing pages instead of burying them deep in + the tree. + +## Tone And Terminology + +- Explain package-specific or Macaulay2-specific terms when they are not obvious + from context. +- Prefer concrete nouns and verbs over vague phrases like “this stuff” or + “various things”. +- Keep acknowledgements and contributor lists off user landing pages unless they + are actively maintained and clearly belong there. + +## Verification Standard + +Before merge, documentation changes should satisfy these expectations: + +- the page was previewed in rendered form when practical +- links and cross-references were checked +- examples were rerun when the change affects them +- the PR states what was verified and what was not diff --git a/README.md b/README.md index c70f11a7ee1..93e2732203f 100644 --- a/README.md +++ b/README.md @@ -33,8 +33,10 @@ For the documentation refresh workflow on this fork: * State what you verified locally, especially for examples, links, and regenerated documentation pages. -See [DocumentationPlan.md](DocumentationPlan.md) for the current documentation -workflow, issue taxonomy, and local preview guidance. +See [DocumentationPlan.md](DocumentationPlan.md), +[DocumentationGuide.md](DocumentationGuide.md), and +[DocumentationStyleGuide.md](DocumentationStyleGuide.md) for the current +documentation workflow, contributor guidance, and documentation standards. To start working on an existing github "issue", volunteer to work on it, so you can get "assigned" to the issue, thereby preventing duplication of From 94583e7f72c56523c3d064bb27ef58913108ff6f Mon Sep 17 00:00:00 2001 From: aalmousa Date: Sat, 25 Apr 2026 12:14:23 -0400 Subject: [PATCH 06/73] Align documentation guides with upstream docs style --- DocumentationGuide.md | 23 ++++++++++++++++++++ DocumentationStyleGuide.md | 44 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) diff --git a/DocumentationGuide.md b/DocumentationGuide.md index cb906700163..dd53daf2ef5 100644 --- a/DocumentationGuide.md +++ b/DocumentationGuide.md @@ -4,6 +4,15 @@ This guide is for contributors working on the documentation refresh in `aalmousa/M2`. Use it together with [DocumentationPlan.md](DocumentationPlan.md) and [DocumentationStyleGuide.md](DocumentationStyleGuide.md). +The repo-local guides are aligned with these upstream documentation references: + +- +- + +Use the upstream pages for the full package-writing and documentation syntax +details. Use this guide for the branch workflow, local preview, and review +expectations for the documentation refresh. + ## Scope The main documentation surfaces in this repository are: @@ -16,6 +25,14 @@ The main documentation surfaces in this repository are: Edit source documentation, not generated html. +Macaulay2 documentation is written in one of two supported forms: + +- `document(List)` using the list-based hypertext format +- `doc(String)` using the string-based `SimpleDoc` format + +Documentation entries belong to a package and should occur after that package's +`beginDocumentation()` section. + ## Workflow 1. Claim or create an issue in `aalmousa/M2` and track it in the @@ -70,6 +87,12 @@ make -C "$M2BUILDDIR/Macaulay2/packages" \ For package docs, also use `viewHelp` or `installPackage` when that is the quickest way to confirm the rendered result. +For a normal documentation-writing cycle, the built-in documentation recommends: + +1. edit the documentation source +2. run `installPackage("YourPackage")` +3. review the result with `viewHelp` + Reserve the expensive flags for final verification: - `RunExamples => false`: fastest preview for text-only edits diff --git a/DocumentationStyleGuide.md b/DocumentationStyleGuide.md index b564a6ba0eb..a7637b0ac25 100644 --- a/DocumentationStyleGuide.md +++ b/DocumentationStyleGuide.md @@ -3,6 +3,14 @@ This guide sets the documentation standards for the refresh on `doc-updates`. It is intentionally short and operational. +It is a repo-local companion to the upstream Macaulay2 documentation guidance: + +- +- + +This file adopts the documentation-specific rules from those sources. Broader +package-coding and naming rules still live in the upstream wiki. + ## Priorities 1. Optimize for a mathematically literate user trying to accomplish something. @@ -19,6 +27,8 @@ It is intentionally short and operational. they are still relevant. - If a symbol or page is important enough to export, it should normally be documented rather than left behind `undocumented`. +- Use Unicode where appropriate, such as in authors' names or mathematically + standard terminology. ## Page Types @@ -34,7 +44,15 @@ When the doc surface supports it, include: - at least one example or a strong cross-reference - `SeeAlso` +The `Headline` should be a brief phrase, not a complete sentence, and should +avoid referring to variables by name when possible. + If an option materially changes behavior, document the option node too. +For method functions, document the return type when possible so the +documentation generator can place the method in the right type-level views. +In `Outputs`, say not only the type but also what mathematical object or value +is returned. Use multiple output entries only when the function actually +returns a sequence with multiple components. ### Package Landing Pages @@ -60,12 +78,31 @@ A package landing page should answer these questions quickly: - Point readers toward the right source file or build context. - Do not pretend an internal page is a user-facing landing page. +## Conventions From Built-In Documentation + +- Use lowercase for titles and headlines unless a proper noun requires + capitalization. +- Use `TO` to reference Macaulay2 functions, options, variables, packages, and + related documentation nodes as hyperlinks. +- `Inputs`, `Outputs`, and `Consequences` entries should not end with periods. +- Prefer the existing documentation templates and page shapes already used in + `PackageTemplate.m2`, `Macaulay2Doc`, and `SimpleDoc`. + ## Examples - Prefer one minimal example and one slightly richer example over a long dump. - Examples should be runnable when practical. - If output is expensive, unstable, or externally dependent, say so explicitly. - Do not leave an example block in place if it has become misleading. +- Each exported data type, method, and function should have a documentation + page, and each documentation page should normally include an example. +- Choose examples that illustrate usage clearly without consuming excessive CPU + time or memory. +- Do not place multiple large example blocks back-to-back without explanatory + text between them. +- Do not reload the package being documented inside example code. +- In `Usage` and `Outputs`, avoid assigning a single returned value to a + variable unless that assignment is needed to explain a later step. ## Navigation And Cross-References @@ -81,6 +118,13 @@ A package landing page should answer these questions quickly: from context. - Prefer concrete nouns and verbs over vague phrases like “this stuff” or “various things”. +- Start sentences with English words, not identifiers or symbols. +- Use Macaulay2 identifiers as code references, not as English words in prose. +- Use lowercase common nouns like “list” or “hash table” unless you are naming + the class `List` or `HashTable`. +- End prose sentences with periods or question marks, not with a colon used in + place of a sentence. +- Make each sentence a real sentence with a subject and a verb. - Keep acknowledgements and contributor lists off user landing pages unless they are actively maintained and clearly belong there. From 267d05f62dc2ee506df9d15849583dd3722e419d Mon Sep 17 00:00:00 2001 From: aalmousa Date: Sat, 25 Apr 2026 12:24:32 -0400 Subject: [PATCH 07/73] Shorten documentation style guide --- DocumentationStyleGuide.md | 147 +++++++++++++++---------------------- 1 file changed, 61 insertions(+), 86 deletions(-) diff --git a/DocumentationStyleGuide.md b/DocumentationStyleGuide.md index a7637b0ac25..a18f8a0a9c7 100644 --- a/DocumentationStyleGuide.md +++ b/DocumentationStyleGuide.md @@ -1,38 +1,34 @@ # Documentation Style Guide -This guide sets the documentation standards for the refresh on `doc-updates`. -It is intentionally short and operational. +Use this guide for documentation work on `doc-updates`. -It is a repo-local companion to the upstream Macaulay2 documentation guidance: +It follows the documentation-specific guidance in: - - -This file adopts the documentation-specific rules from those sources. Broader -package-coding and naming rules still live in the upstream wiki. +For broader package-coding rules, use the upstream wiki. -## Priorities +## What Good Documentation Must Do -1. Optimize for a mathematically literate user trying to accomplish something. -2. Make the next step obvious. -3. Keep examples trustworthy. +- Help a mathematically literate user do the next thing quickly. +- Make the next useful page, package, or example easy to find. +- Stay accurate for the current code. +- Keep examples small, clear, and trustworthy. -## General Rules +## Required Standards -- Write for the page's audience, not for someone already reading the source. -- Prefer direct present-tense statements over historical notes or speculation. - Do not leave `TODO`, `FIXME`, `Section XX`, or references to missing follow-up tutorials in user-facing pages. -- Avoid stale course framing, version-era notes, or performance caveats unless - they are still relevant. -- If a symbol or page is important enough to export, it should normally be - documented rather than left behind `undocumented`. -- Use Unicode where appropriate, such as in authors' names or mathematically - standard terminology. - -## Page Types +- Avoid stale course framing, old version-era notes, and obsolete performance + caveats unless they still matter. +- If a symbol is exported, it should normally be documented rather than left + `undocumented`. +- Every new page should be reachable from at least one parent page. +- Preview the rendered page when practical, and check links and cross-references + before merge. -### Function And Method Pages +## Function And Method Pages When the doc surface supports it, include: @@ -40,21 +36,24 @@ When the doc surface supports it, include: - `Usage` - `Inputs` - `Outputs` -- a short explanation of behavior and context +- a short explanation of behavior - at least one example or a strong cross-reference - `SeeAlso` -The `Headline` should be a brief phrase, not a complete sentence, and should -avoid referring to variables by name when possible. +Use these conventions: -If an option materially changes behavior, document the option node too. -For method functions, document the return type when possible so the -documentation generator can place the method in the right type-level views. -In `Outputs`, say not only the type but also what mathematical object or value -is returned. Use multiple output entries only when the function actually -returns a sequence with multiple components. +- Keep titles and headlines lowercase unless a proper noun requires capitals. +- Make the `Headline` a short phrase, not a full sentence. +- Use `TO` for links to functions, options, variables, packages, and doc nodes. +- Do not end `Inputs`, `Outputs`, or `Consequences` entries with periods. +- In `Outputs`, say both the type and what mathematical object or value is + returned. +- For method functions, document the return type when possible. +- If an option materially changes behavior, document the option node too. +- Prefer the existing page shapes already used in `PackageTemplate.m2`, + `Macaulay2Doc`, and `SimpleDoc`. -### Package Landing Pages +## Package Landing Pages A package landing page should answer these questions quickly: @@ -64,75 +63,51 @@ A package landing page should answer these questions quickly: - Where should a new user start? - Where are the main examples or tutorials? -### Tutorials +## Tutorials -- State the goal of the tutorial early. +- State the goal near the top. - Say what packages need to be loaded. - Present examples in an order a reader can follow. -- Separate tutorial guidance from raw test material. -- If a tutorial assumes external software, say so near the top. +- Keep explanatory text separate from raw test material. +- If external software or setup is required, say so early. -### Internal Or Generated Docs +## Internal Or Generated Docs - Say whether the page is hand-maintained or generated. -- Point readers toward the right source file or build context. -- Do not pretend an internal page is a user-facing landing page. +- Point readers to the right source file or build context. +- Do not present an internal page as a user-facing landing page. -## Conventions From Built-In Documentation +## Writing Rules -- Use lowercase for titles and headlines unless a proper noun requires - capitalization. -- Use `TO` to reference Macaulay2 functions, options, variables, packages, and - related documentation nodes as hyperlinks. -- `Inputs`, `Outputs`, and `Consequences` entries should not end with periods. -- Prefer the existing documentation templates and page shapes already used in - `PackageTemplate.m2`, `Macaulay2Doc`, and `SimpleDoc`. +- Write for the page's audience, not for someone already reading the source. +- Prefer direct present-tense statements. +- Explain package-specific or Macaulay2-specific terms when they are not + obvious. +- Use Macaulay2 identifiers as code references, not as English words in prose. +- Start sentences with English words, not identifiers or symbols. +- Use lowercase common nouns like “list” or “hash table” unless you mean the + class `List` or `HashTable`. +- Write real sentences with normal punctuation. +- Use Unicode where appropriate. +- Keep contributor lists off user landing pages unless they are actively + maintained and clearly belong there. ## Examples +- Each documented exported data type, method, and function should normally have + at least one example. - Prefer one minimal example and one slightly richer example over a long dump. -- Examples should be runnable when practical. +- Choose examples that show real usage without consuming excessive CPU time or + memory. - If output is expensive, unstable, or externally dependent, say so explicitly. -- Do not leave an example block in place if it has become misleading. -- Each exported data type, method, and function should have a documentation - page, and each documentation page should normally include an example. -- Choose examples that illustrate usage clearly without consuming excessive CPU - time or memory. -- Do not place multiple large example blocks back-to-back without explanatory - text between them. -- Do not reload the package being documented inside example code. +- Do not place large example blocks back-to-back without explanation. +- Do not reload the package being documented inside examples. - In `Usage` and `Outputs`, avoid assigning a single returned value to a variable unless that assignment is needed to explain a later step. -## Navigation And Cross-References +## Before Merge -- Every new page should be reachable from at least one parent page. -- `SeeAlso`, `Subnodes`, and top-level navigation should point somewhere useful. -- Avoid orphan pages and commented-out navigation. -- Surface high-value guides from landing pages instead of burying them deep in - the tree. - -## Tone And Terminology - -- Explain package-specific or Macaulay2-specific terms when they are not obvious - from context. -- Prefer concrete nouns and verbs over vague phrases like “this stuff” or - “various things”. -- Start sentences with English words, not identifiers or symbols. -- Use Macaulay2 identifiers as code references, not as English words in prose. -- Use lowercase common nouns like “list” or “hash table” unless you are naming - the class `List` or `HashTable`. -- End prose sentences with periods or question marks, not with a colon used in - place of a sentence. -- Make each sentence a real sentence with a subject and a verb. -- Keep acknowledgements and contributor lists off user landing pages unless they - are actively maintained and clearly belong there. - -## Verification Standard - -Before merge, documentation changes should satisfy these expectations: - -- the page was previewed in rendered form when practical -- links and cross-references were checked -- examples were rerun when the change affects them -- the PR states what was verified and what was not +- the page renders correctly, or `viewHelp` shows the expected result +- links, `SeeAlso`, `Subnodes`, and top-level navigation were checked +- examples were rerun when the change affects them, or the PR explains why not +- the PR says what was verified and what was not From 2e42f75ed5467336caf97826365e7cfa7c4bd340 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Sat, 25 Apr 2026 12:34:59 -0400 Subject: [PATCH 08/73] Add remaining docs refresh backlog gaps --- DocumentationPlan.md | 47 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/DocumentationPlan.md b/DocumentationPlan.md index b19622333a7..2932b46c0bd 100644 --- a/DocumentationPlan.md +++ b/DocumentationPlan.md @@ -461,6 +461,53 @@ triage. Done when: at least five narrowly scoped doc issues are labeled and ready to assign. +### Project Infrastructure And Discoverability + +46. Add fast CI checks for documentation pull requests to `doc-updates`. + Paths: `.github/workflows/`, `.github/actions/`, contributor docs as needed + Done when: documentation PRs get a lightweight automated check for obvious + failures such as broken scoped doc builds, broken links or cross-references + in changed documentation, and basic text-level regressions without forcing + every PR through a full package-example or full-site rebuild. + +47. Audit undocumented exported symbols across distributed packages. + Paths: `M2/Macaulay2/packages/`, package export lists, generated docs as + needed + Done when: exported symbols lacking documentation are summarized in a + tracked report or split into child issues by package or topic, and the + backlog clearly distinguishes between intentionally undocumented internals + and user-facing exports that still need documentation. + +48. Standardize external prerequisite documentation across packages. + Paths: package landing pages, READMEs, and doc nodes for packages that rely + on external software or services + Done when: packages with external prerequisites describe those dependencies + in a consistent place and format, including how to install or verify the + prerequisite and what functionality depends on it. + +49. Improve concept-to-command discoverability in the documentation. + Paths: `M2/Macaulay2/packages/Macaulay2Doc/`, package landing pages, and + related navigation pages + Done when: users who know a mathematical object or task but not the + relevant Macaulay2 command have a clearer path through topic pages, + cross-references, or index-style guides to the right reference entries and + examples. + +50. Document how repository changes become updates on `macaulay2.com`. + Paths: repo-local contributor docs, release/deployment docs if present, and + upstream process references as needed + Done when: contributors can tell what must happen after a documentation PR + lands for the live website to change, including which steps are local to + the repo, which depend on upstream maintainers, and where deployment or + publishing responsibility currently lives. + +51. Define reviewer routing for package, tutorial, and math-heavy documentation changes. + Paths: repo-local contributor docs, labels, and review workflow docs + Done when: contributors know when to request package-owner review, + `needs-math-review`, example reruns, or editorial review, and the review + expectations are documented in one repo-local place rather than spread + across issue comments. + ## Notes For Leads 1. Keep the integration branch stable enough that people can branch from it From fe4190b269d607e2b03689cb054037a8d68c943b Mon Sep 17 00:00:00 2001 From: Ayah Almousa <38053754+aalmousa@users.noreply.github.com> Date: Thu, 14 May 2026 15:50:45 -0400 Subject: [PATCH 09/73] Add Macaulay2Doc landing page refresh plan --- .../Macaulay2Doc-landing-page-refresh-plan.md | 361 ++++++++++++++++++ 1 file changed, 361 insertions(+) create mode 100644 M2/Macaulay2/Macaulay2Doc-landing-page-refresh-plan.md diff --git a/M2/Macaulay2/Macaulay2Doc-landing-page-refresh-plan.md b/M2/Macaulay2/Macaulay2Doc-landing-page-refresh-plan.md new file mode 100644 index 00000000000..84e4b1dff9d --- /dev/null +++ b/M2/Macaulay2/Macaulay2Doc-landing-page-refresh-plan.md @@ -0,0 +1,361 @@ +# Macaulay2Doc Landing Page Refresh Plan + +## Summary + +Rework the `Macaulay2Doc` landing page from a mostly subject-first table of contents into four audience-first hubs: + +1. Getting Started +2. For the Working Mathematician +3. For Contributors +4. For Advanced Users + +These sections should act as curated entry points into the existing documentation, not as strict partitions of the entire docs tree. Existing reference and tutorial nodes should remain reusable, and a given node may appear in more than one hub when that makes the navigation clearer. + +The main goal is to add an audience layer above the current overview and reference material, rather than rewriting all deep reference pages at once. + +## Current Structure + +The current top-level landing page is defined in `packages/Macaulay2Doc/ov_top.m2`. + +The current main sections are: + +- Getting Started +- Reference Manual +- Mathematical Objects +- Mathematical Tutorials +- Mathematical Computations +- Appendix + +Relevant existing overview sources already include: + +- `ov_getting_started.m2` +- `ov_first_session.m2` +- `ov_language.m2` +- `ov_packages.m2` +- `ov_documentation.m2` +- `ov_developers.m2` +- `ov_rings.m2` +- `ov_ideals.m2` +- `ov_matrices.m2` +- `ov_modules.m2` +- `ov_ringmaps.m2` +- `ov_lists.m2` +- `ov_hashtables.m2` +- `ov_types.m2` +- `ov_methods.m2` +- `ov_debugging.m2` +- `ov_system.m2` +- `ov_threads.m2` + +The load order is controlled by `packages/Macaulay2Doc/loads.m2`, so any structural refresh should be reflected there as well. + +## Audience-Hub Architecture + +### 1. Getting Started + +This section should answer: + +> I installed Macaulay2. How do I begin, how do I interact with it, and how do I get unstuck? + +Use these existing nodes directly: + +- `setting up Macaulay2` +- `a first Macaulay2 session` +- `reading the documentation` +- `getting help or reporting bugs` +- `using Macaulay2 with Emacs` +- `using Macaulay2 in a terminal` +- `invoking the Macaulay2 program` + +Add these new overview nodes: + +- `Getting Started with Macaulay2` + - A short front-door guide that links to installation, first session, editors, help, and reading the docs. +- `First mathematical workflow in Macaulay2` + - A short path showing how to define a ring, build an ideal, compute something, inspect the output, and look up more help. +- `How to choose a data type` + - A practical guide for common user choices such as `List` vs `Sequence` vs `MutableList`, `HashTable` vs `MutableHashTable`, `Set`, and matrices vs mutable matrices. + +This should be the only section that is fully beginner-safe. + +### 2. For the Working Mathematician + +This section should answer: + +> I want to do mathematics in Macaulay2. Where are the main objects, computations, tutorials, and packages? + +Use these existing nodes: + +- `rings` +- `ideals` +- `matrices` +- `modules` +- `morphisms` +- `chain complexes` +- `varieties and sheaves` +- `commutative algebra` +- `homological algebra` +- `algebraic geometry` +- `combinatorics` +- `analytic functions` +- `packages provided with Macaulay2` + +Use these current tutorial nodes: + +- `A first course in commutative algebra` +- `Tutorial: Modules in Macaulay2` +- `Tutorial: Elementary uses of Gröbner bases` +- `Tutorial: Canonical Embeddings of Plane Curves and Gonality` +- `Tutorial: Fano varieties` +- `Tutorial: Divisors` + +Add these new overview nodes: + +- `Mathematics in Macaulay2` + - The main hub for mathematical workflows. +- `Core mathematical objects` + - A guide explaining the relationship between rings, ideals, matrices, modules, maps, and complexes. +- `Finding the right package` + - A package-discovery hub pointing into `packages provided with Macaulay2`. + +This section should replace the current split between `Mathematical Objects`, `Mathematical Tutorials`, and `Mathematical Computations` on the landing page. + +### 3. For Contributors + +This section should answer: + +> How do I add or improve things in Macaulay2? + +Use these existing nodes: + +- `creating a package` +- `packages` +- `writing documentation` +- `SimpleDoc :: SimpleDoc` +- `installPackage` +- `check Package` +- `debug Package` +- `The authors of Macaulay2 packages` +- `Core` +- `the interpreter of Macaulay2` +- `the engine of Macaulay2` +- `how Macaulay2 finds its files` + +Add these new overview nodes: + +- `Contributing to Macaulay2` + - The main contributor hub. +- `Contributing a package` + - A package-author path covering structure, exports, docs, tests, install/check, and pull requests. +- `Contributing documentation` + - A docs-author path covering hypertext/simpledoc, `installPackage`, review cycle, and style conventions. +- `Contributing to the core system` + - An orientation node for core, interpreter, engine, build, and runtime layout. +- `Documentation refresh project` + - Optional tracker-style node if the docs refresh effort should be visible from the documentation itself. + +This section should make three contributor tracks explicit: + +- package contributors +- documentation contributors +- core contributors + +### 4. For Advanced Users + +This section should answer: + +> I already use Macaulay2. How do I understand the language, types, methods, debugging, system behavior, and performance-oriented features? + +Use these existing nodes: + +- `The Macaulay2 language` +- `basic data types` +- `strings and nets` +- `lists and sequences` +- `hash tables` +- `what a class is` +- `installing methods` +- `inheritance` +- `making new classes` +- `making a new method function` +- `debugging` +- `the debugger` +- `parallel programming with threads and tasks` +- `system facilities` +- `how Macaulay2 finds its files` + +Add these new overview nodes: + +- `Advanced use of Macaulay2` + - The main hub for language internals and power-user workflows. +- `Data types and mutability` + - A bridge from beginner-facing type guidance into deeper type documentation. +- `Methods, dispatch, and classes` + - A guide into `what a class is`, method installation, and inheritance. +- `Debugging and introspection` + - A guide into debugging, backtraces, and package debugging. +- `System layout and runtime behavior` + - A guide into startup, file layout, package loading, and the application directory. +- `Parallelism and performance` + - A guide into threads, tasks, and engine parallelism. + +This section should replace the current experience of burying language and power-user material under `Reference Manual`. + +## Proposed New Nodes + +The first wave of new high-value overview nodes should be: + +- `Getting Started with Macaulay2` +- `First mathematical workflow in Macaulay2` +- `How to choose a data type` +- `Mathematics in Macaulay2` +- `Core mathematical objects` +- `Finding the right package` +- `Contributing to Macaulay2` +- `Contributing a package` +- `Contributing documentation` +- `Contributing to the core system` +- `Advanced use of Macaulay2` +- `Data types and mutability` +- `Methods, dispatch, and classes` +- `Debugging and introspection` +- `System layout and runtime behavior` +- `Parallelism and performance` + +The highest-priority new node should be `How to choose a data type`, because it fills a real navigation gap for both beginners and advanced users. + +## Proposed Source Tree + +To support the new audience layer, reorganize the `packages/Macaulay2Doc/` overview sources around hubs and guides. + +Recommended layout: + +```text +packages/Macaulay2Doc/ + landing/ + home.m2 + audience/ + getting_started.m2 + working_mathematician.m2 + contributors.m2 + advanced_users.m2 + guides/ + guide_first_workflow.m2 + guide_choose_data_type.m2 + guide_core_objects.m2 + guide_find_package.m2 + guide_contributing_package.m2 + guide_contributing_docs.m2 + guide_contributing_core.m2 + guide_methods_dispatch.m2 + guide_debugging_introspection.m2 + guide_system_runtime.m2 + guide_parallelism_performance.m2 + subjects/ + ov_rings.m2 + ov_ideals.m2 + ov_matrices.m2 + ov_modules.m2 + ov_ringmaps.m2 + ov_analytic_functions.m2 + ov_groebner_bases.m2 + ... + language/ + ov_language.m2 + ov_lists.m2 + ov_hashtables.m2 + ov_types.m2 + ov_methods.m2 + ov_debugging.m2 + ov_system.m2 + ov_threads.m2 + contributors/ + ov_packages.m2 + ov_documentation.m2 + ov_developers.m2 + tutorials/ + tu_modules.m2 + tu_elementary.m2 + tu_canEmbed.m2 + tu_divisors.m2 + tu_Fano.m2 + ... +``` + +This is a target structure, not a requirement for a single PR. The initial refresh can create the audience and guide layers first, then move files incrementally. + +## Implementation Notes + +### Landing Page + +- Replace the current monolithic top-page structure in `ov_top.m2` with an audience-first landing page. +- The landing page should be short and scannable. +- Each section should include: + - a one-sentence audience description + - a small number of high-signal entry links + - optionally, one short paragraph clarifying how to use that section + +### `ov_top.m2` + +- `ov_top.m2` should stop being the only place where overall documentation structure lives. +- It should become either: + - a thin home-page file, or + - a wrapper that links to the four audience hubs + +The reusable structure should be moved into the new audience and guide files. + +### `loads.m2` + +Revise `loads.m2` to load by layer: + +1. landing page +2. audience hubs +3. guide nodes +4. subject overviews +5. language and advanced overviews +6. contributor overviews +7. deep reference and tutorial material + +This will make the documentation structure easier to maintain and reason about. + +### Node Strategy + +- The new audience hubs should be first-class nodes. +- Deep reference nodes should remain reusable link targets. +- Avoid unnecessary churn in existing deep reference nodes. +- The main restructure should happen at the hub and overview layer. + +## Test and Verification Plan + +After implementation, verify: + +- `Macaulay2Doc` builds successfully. +- The new landing page renders correctly in generated HTML. +- The new audience hubs are visible and easy to scan. +- Every link from the landing page and the four hubs resolves correctly. +- The new `How to choose a data type` node links correctly into: + - `lists and sequences` + - `hash tables` + - `what a class is` + - mutable-matrix documentation +- Tutorials remain reachable from the mathematician hub. +- Contributor hubs point to working package, documentation, and core entry nodes. +- `loads.m2` order still yields a sensible table of contents. + +## Assumptions and Defaults + +- This is a broader structural refresh, not just a visual rewrite of the current top page. +- The four sections are audience hubs, not strict partitions. +- Duplication of links across sections is intentional when it improves navigation. +- Deep reference nodes should mostly remain intact. +- URL and node-title compatibility are not the primary constraint, but unnecessary deep-node churn should still be avoided. +- The first new content node to add should be `How to choose a data type`. + +## Suggested Rollout Order + +1. Add the planning note and agree on the audience-hub structure. +2. Refactor the landing page into the four hubs without rewriting all deeper docs. +3. Add `How to choose a data type`. +4. Add the other missing guide nodes. +5. Reorganize source files and `loads.m2` incrementally. +6. Polish cross-linking and reduce dead-end nodes. From 81c33d014009cf1e0d3c11154793f4deb181ed02 Mon Sep 17 00:00:00 2001 From: Ayah Almousa <38053754+aalmousa@users.noreply.github.com> Date: Thu, 14 May 2026 15:59:00 -0400 Subject: [PATCH 10/73] Merge documentation guide and style guide --- DocumentationGuide.md | 111 +++++++++++++++++++++++++++++++++++- DocumentationPlan.md | 4 +- DocumentationStyleGuide.md | 113 ------------------------------------- README.md | 7 +-- 4 files changed, 113 insertions(+), 122 deletions(-) delete mode 100644 DocumentationStyleGuide.md diff --git a/DocumentationGuide.md b/DocumentationGuide.md index dd53daf2ef5..cd7127f29a0 100644 --- a/DocumentationGuide.md +++ b/DocumentationGuide.md @@ -1,8 +1,7 @@ # Documentation Guide This guide is for contributors working on the documentation refresh in -`aalmousa/M2`. Use it together with [DocumentationPlan.md](DocumentationPlan.md) -and [DocumentationStyleGuide.md](DocumentationStyleGuide.md). +`aalmousa/M2`. Use it together with [DocumentationPlan.md](DocumentationPlan.md). The repo-local guides are aligned with these upstream documentation references: @@ -11,7 +10,8 @@ The repo-local guides are aligned with these upstream documentation references: Use the upstream pages for the full package-writing and documentation syntax details. Use this guide for the branch workflow, local preview, and review -expectations for the documentation refresh. +expectations for the documentation refresh, along with the repo-local +documentation standards that reviewers should enforce. ## Scope @@ -33,6 +33,13 @@ Macaulay2 documentation is written in one of two supported forms: Documentation entries belong to a package and should occur after that package's `beginDocumentation()` section. +## What Good Documentation Must Do + +- Help a mathematically literate user do the next thing quickly. +- Make the next useful page, package, or example easy to find. +- Stay accurate for the current code. +- Keep examples small, clear, and trustworthy. + ## Workflow 1. Claim or create an issue in `aalmousa/M2` and track it in the @@ -43,6 +50,98 @@ Documentation entries belong to a package and should occur after that package's 5. If the scope grows, split follow-up work into new issues instead of widening the PR. +## Documentation Standards + +### Required Standards + +- Do not leave `TODO`, `FIXME`, `Section XX`, or references to missing + follow-up tutorials in user-facing pages. +- Avoid stale course framing, old version-era notes, and obsolete performance + caveats unless they still matter. +- If a symbol is exported, it should normally be documented rather than left + `undocumented`. +- Every new page should be reachable from at least one parent page. +- Preview the rendered page when practical, and check links and + cross-references before merge. + +### Function And Method Pages + +When the documentation surface supports it, include: + +- `Headline` +- `Usage` +- `Inputs` +- `Outputs` +- a short explanation of behavior +- at least one example or a strong cross-reference +- `SeeAlso` + +Use these conventions: + +- Keep titles and headlines lowercase unless a proper noun requires capitals. +- Make the `Headline` a short phrase, not a full sentence. +- Use `TO` for links to functions, options, variables, packages, and doc + nodes. +- Do not end `Inputs`, `Outputs`, or `Consequences` entries with periods. +- In `Outputs`, say both the type and what mathematical object or value is + returned. +- For method functions, document the return type when possible. +- If an option materially changes behavior, document the option node too. +- Prefer the page shapes already used in `PackageTemplate.m2`, `Macaulay2Doc`, + and `SimpleDoc`. + +### Package Landing Pages + +A package landing page should answer these questions quickly: + +- What does the package do? +- What package needs to be loaded? +- Are there external prerequisites? +- Where should a new user start? +- Where are the main examples or tutorials? + +### Tutorials + +- State the goal near the top. +- Say what packages need to be loaded. +- Present examples in an order a reader can follow. +- Keep explanatory text separate from raw test material. +- If external software or setup is required, say so early. + +### Internal Or Generated Docs + +- Say whether the page is hand-maintained or generated. +- Point readers to the right source file or build context. +- Do not present an internal page as a user-facing landing page. + +### Writing Rules + +- Write for the page's audience, not for someone already reading the source. +- Prefer direct present-tense statements. +- Explain package-specific or Macaulay2-specific terms when they are not + obvious. +- Use Macaulay2 identifiers as code references, not as English words in prose. +- Start sentences with English words, not identifiers or symbols. +- Use lowercase common nouns like `list` or `hash table` unless you mean the + class `List` or `HashTable`. +- Write real sentences with normal punctuation. +- Use Unicode where appropriate. +- Keep contributor lists off user landing pages unless they are actively + maintained and clearly belong there. + +### Examples + +- Each documented exported data type, method, and function should normally have + at least one example. +- Prefer one minimal example and one slightly richer example over a long dump. +- Choose examples that show real usage without consuming excessive CPU time or + memory. +- If output is expensive, unstable, or externally dependent, say so explicitly. +- Do not place large example blocks back-to-back without explanation. +- Do not reload the package being documented inside examples. +- In `Usage` and `Outputs`, avoid assigning a single returned value to a + variable unless that assignment is needed to explain a later step. + ## Before Editing - Identify the audience first: end user, package user, contributor, or internal @@ -114,6 +213,12 @@ Every documentation PR should say what was checked locally. Use this checklist: - any external prerequisite or setup instructions were checked against current reality +Before merge, also confirm: + +- the PR says what was verified and what was not +- the change matches the current audience and page type +- any unresolved uncertainty about examples or outputs is stated plainly + ## Labels And Review Use the repo labels to keep work triageable: diff --git a/DocumentationPlan.md b/DocumentationPlan.md index 2932b46c0bd..1bf3458ec4e 100644 --- a/DocumentationPlan.md +++ b/DocumentationPlan.md @@ -24,8 +24,8 @@ workflow, and the first backlog to turn into issues. 5. Land focused pull requests into `doc-updates`, not one large omnibus PR. 6. Close the issue only after review and any needed follow-up verification. -Contributor-facing guidance lives in [DocumentationGuide.md](DocumentationGuide.md) -and [DocumentationStyleGuide.md](DocumentationStyleGuide.md). +Contributor-facing guidance lives in +[DocumentationGuide.md](DocumentationGuide.md). ## Suggested Labels diff --git a/DocumentationStyleGuide.md b/DocumentationStyleGuide.md deleted file mode 100644 index a18f8a0a9c7..00000000000 --- a/DocumentationStyleGuide.md +++ /dev/null @@ -1,113 +0,0 @@ -# Documentation Style Guide - -Use this guide for documentation work on `doc-updates`. - -It follows the documentation-specific guidance in: - -- -- - -For broader package-coding rules, use the upstream wiki. - -## What Good Documentation Must Do - -- Help a mathematically literate user do the next thing quickly. -- Make the next useful page, package, or example easy to find. -- Stay accurate for the current code. -- Keep examples small, clear, and trustworthy. - -## Required Standards - -- Do not leave `TODO`, `FIXME`, `Section XX`, or references to missing follow-up - tutorials in user-facing pages. -- Avoid stale course framing, old version-era notes, and obsolete performance - caveats unless they still matter. -- If a symbol is exported, it should normally be documented rather than left - `undocumented`. -- Every new page should be reachable from at least one parent page. -- Preview the rendered page when practical, and check links and cross-references - before merge. - -## Function And Method Pages - -When the doc surface supports it, include: - -- `Headline` -- `Usage` -- `Inputs` -- `Outputs` -- a short explanation of behavior -- at least one example or a strong cross-reference -- `SeeAlso` - -Use these conventions: - -- Keep titles and headlines lowercase unless a proper noun requires capitals. -- Make the `Headline` a short phrase, not a full sentence. -- Use `TO` for links to functions, options, variables, packages, and doc nodes. -- Do not end `Inputs`, `Outputs`, or `Consequences` entries with periods. -- In `Outputs`, say both the type and what mathematical object or value is - returned. -- For method functions, document the return type when possible. -- If an option materially changes behavior, document the option node too. -- Prefer the existing page shapes already used in `PackageTemplate.m2`, - `Macaulay2Doc`, and `SimpleDoc`. - -## Package Landing Pages - -A package landing page should answer these questions quickly: - -- What does the package do? -- What package needs to be loaded? -- Are there external prerequisites? -- Where should a new user start? -- Where are the main examples or tutorials? - -## Tutorials - -- State the goal near the top. -- Say what packages need to be loaded. -- Present examples in an order a reader can follow. -- Keep explanatory text separate from raw test material. -- If external software or setup is required, say so early. - -## Internal Or Generated Docs - -- Say whether the page is hand-maintained or generated. -- Point readers to the right source file or build context. -- Do not present an internal page as a user-facing landing page. - -## Writing Rules - -- Write for the page's audience, not for someone already reading the source. -- Prefer direct present-tense statements. -- Explain package-specific or Macaulay2-specific terms when they are not - obvious. -- Use Macaulay2 identifiers as code references, not as English words in prose. -- Start sentences with English words, not identifiers or symbols. -- Use lowercase common nouns like “list” or “hash table” unless you mean the - class `List` or `HashTable`. -- Write real sentences with normal punctuation. -- Use Unicode where appropriate. -- Keep contributor lists off user landing pages unless they are actively - maintained and clearly belong there. - -## Examples - -- Each documented exported data type, method, and function should normally have - at least one example. -- Prefer one minimal example and one slightly richer example over a long dump. -- Choose examples that show real usage without consuming excessive CPU time or - memory. -- If output is expensive, unstable, or externally dependent, say so explicitly. -- Do not place large example blocks back-to-back without explanation. -- Do not reload the package being documented inside examples. -- In `Usage` and `Outputs`, avoid assigning a single returned value to a - variable unless that assignment is needed to explain a later step. - -## Before Merge - -- the page renders correctly, or `viewHelp` shows the expected result -- links, `SeeAlso`, `Subnodes`, and top-level navigation were checked -- examples were rerun when the change affects them, or the PR explains why not -- the PR says what was verified and what was not diff --git a/README.md b/README.md index 3a59072b3cf..406cf043f3e 100644 --- a/README.md +++ b/README.md @@ -32,10 +32,9 @@ For the documentation refresh workflow on this fork: * State what you verified locally, especially for examples, links, and regenerated documentation pages. -See [DocumentationPlan.md](DocumentationPlan.md), -[DocumentationGuide.md](DocumentationGuide.md), and -[DocumentationStyleGuide.md](DocumentationStyleGuide.md) for the current -documentation workflow, contributor guidance, and documentation standards. +See [DocumentationPlan.md](DocumentationPlan.md) and +[DocumentationGuide.md](DocumentationGuide.md) for the current documentation +workflow, contributor guidance, and documentation standards. To start working on an existing github "issue", volunteer to work on it, so you can get "assigned" to the issue, thereby preventing duplication of From 62373cade5b4fe82d1b87e99c835d1f1b9996fa1 Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Sun, 17 May 2026 11:38:44 -0400 Subject: [PATCH 11/73] remove installMinPrimes method that doesnt do anything --- M2/Macaulay2/packages/MinimalPrimes.m2 | 6 +----- M2/Macaulay2/packages/MinimalPrimes/doc.m2 | 2 -- M2/Macaulay2/packages/MultiplicitySequence.m2 | 4 ---- M2/Macaulay2/packages/RandomPoints.m2 | 2 -- 4 files changed, 1 insertion(+), 13 deletions(-) diff --git a/M2/Macaulay2/packages/MinimalPrimes.m2 b/M2/Macaulay2/packages/MinimalPrimes.m2 index b2455ca098f..1446abe8f5b 100644 --- a/M2/Macaulay2/packages/MinimalPrimes.m2 +++ b/M2/Macaulay2/packages/MinimalPrimes.m2 @@ -14,7 +14,6 @@ -- 3. turn strategies into hooks -- 4. which symbols need to be exported -- 5. Binomials package should add binomialMinimalPrimes as a strategy to minimalPrimes --- 6. add installMinprimes that gives a warning --------------------------------------------------------------------------- newPackage( "MinimalPrimes", @@ -67,7 +66,7 @@ newPackage( -- . Document minprimes, something about the strategies -- . Export only the symbols we want -export { "Hybrid", "minimalPrimes", "minprimes" => "minimalPrimes", "radical", "radicalContainment", "installMinprimes" } +export { "Hybrid", "minimalPrimes", "minprimes" => "minimalPrimes", "radical", "radicalContainment"} importFrom_Core { "raw", "rawCharSeries", "rawGBContains", "rawRadical", "newMonomialIdeal" } importFrom_Core { "isComputationDone", "cacheComputation", "fetchComputation", "updateComputation", "cacheHit", "Context", "Computation" } @@ -108,9 +107,6 @@ algorithms = new MutableHashTable from {} -- used for dynamic strategies here and in PrimaryDecomposition Hybrid = new SelfInitializingType of List --- deprecate this soon -installMinprimes = () -> printerr "warning: the installMinprimes routine is now deprecated and should be removed" - -------------------------------------------------------------------- -- Support routines -------------------------------------------------------------------- diff --git a/M2/Macaulay2/packages/MinimalPrimes/doc.m2 b/M2/Macaulay2/packages/MinimalPrimes/doc.m2 index 3f493849ac4..fa9181acb0e 100644 --- a/M2/Macaulay2/packages/MinimalPrimes/doc.m2 +++ b/M2/Macaulay2/packages/MinimalPrimes/doc.m2 @@ -1,5 +1,3 @@ -undocumented { installMinprimes } - doc /// Node Key diff --git a/M2/Macaulay2/packages/MultiplicitySequence.m2 b/M2/Macaulay2/packages/MultiplicitySequence.m2 index e3ce0a75db0..f7ed84dce6d 100644 --- a/M2/Macaulay2/packages/MultiplicitySequence.m2 +++ b/M2/Macaulay2/packages/MultiplicitySequence.m2 @@ -56,8 +56,6 @@ export { "printHilbertSequence" } --- installMinprimes() -- for MinimalPrimes.m2 - getGenElts = method(Options => {symbol minTerms => -1, symbol numCandidates => 3}) getGenElts (Ideal, ZZ) := List => opts -> (I, n) -> ( G := flatten entries mingens I; -- I_*; @@ -737,8 +735,6 @@ installPackage("MultiplicitySequence", RemakeAllDocumentation => true) uninstallPackage "MultiplicitySequence" check "MultiplicitySequence" viewHelp "MultiplicitySequence" -needsPackage "MinimalPrimes" -installMinprimes() debugLevel = 2 elapsedTime multiplicitySequence I diff --git a/M2/Macaulay2/packages/RandomPoints.m2 b/M2/Macaulay2/packages/RandomPoints.m2 index 5ef8006f79d..134ab653a9f 100644 --- a/M2/Macaulay2/packages/RandomPoints.m2 +++ b/M2/Macaulay2/packages/RandomPoints.m2 @@ -69,8 +69,6 @@ export { } exportMutable {} ---installMinprimes(); - --this appears to need to be here, otherwise the options don't realize dimViaBezout is a function, it thinks its a symbol. dimViaBezout=method(Options => { Verbose => false, From 5624dbecec8e61b26c1a7d84e2fd2e795851f216 Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Sun, 17 May 2026 14:10:37 -0400 Subject: [PATCH 12/73] document default startegy and add links --- M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 b/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 index c63c64da557..e118ee26be2 100644 --- a/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 +++ b/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 @@ -430,13 +430,12 @@ Node Invent. Math. 110 (1992) 207-235. However, we use @TO (localize, Ideal, Ideal)@. The @TT "Strategy"@ option value sets the strategy option for @TO localize@, and should be one of the following: - -- TODO: The default value is 2. @UL{ - LI ("Strategy => 0", " -- Uses ", TT "localize", " Strategy 0"), - LI ("Strategy => 1", " -- Uses ", TT "localize", " Strategy 1"), - LI ("Strategy => 2", " -- Uses ", TT "localize", " Strategy 2") - }@ + LI ("Strategy => 0", " -- Uses ", TO "localize", " Strategy 0"), + LI ("Strategy => 1", " -- Uses ", TO "localize", " Strategy 1"), + LI ("Strategy => 2", " -- Uses ", TO "localize", " Strategy 2 - default") + }@ The @TT "Increment"@ option value should be an integer. The algorithm given in Eisenbud-Huneke-Vasconcelos, Invent. Math. 110 (1992) 207-235, relies on @TT "topComponents(I + P^m)"@ From 37289a726145dd01f28e71304376e8d1a77123a2 Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Sun, 17 May 2026 16:48:24 -0400 Subject: [PATCH 13/73] example that breaks with a likely bug --- .../functions/wedgeProduct-doc.m2 | 45 +++++++++++-------- 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2 index d1e90017113..9bdf6183ea6 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2 @@ -2,22 +2,31 @@ --- author(s): --- notes: -document { - Key => {(wedgeProduct,ZZ,ZZ,Module),wedgeProduct}, - Headline => "the exterior multiplication map", - Usage => "wedgeProduct(p,q,F)", - Inputs => { - "p", "q", "F" => "a free module" - }, - Outputs => { - Matrix => {"representing the multiplication map - from ", TT "exteriorPower(p,M) ** exteriorPower(q,M)", " - to ", TT "exteriorPower(p+q,M)"} - }, - EXAMPLE lines /// +doc /// +Key + (wedgeProduct, ZZ, ZZ, Module) + wedgeProduct +Headline + the exterior multiplication map +Usage + wedgeProduct(p, q, F) +Inputs + p:ZZ + q:ZZ + F:Module + must be free +Outputs + :Matrix + representing the multiplication map from @TT "exteriorPower(p, F) ** + exteriorPower(q, F)"@ to @TT "exteriorPower(p+q, F)"@ +Description + Example F = QQ^4 - wedgeProduct(1,1,F) - ///, - SeeAlso => {exteriorPower} - } - + wp = wedgeProduct(1, 1, F) + L = exteriorPower(1, F) + R = exteriorPower(1, F) + wp * (L_0 ** R_0) + wp * (L_0 ** R_1) +SeeAlso + exteriorPower +/// \ No newline at end of file From c2ed7155e085b3f88025fab38fcb4e1521db14f0 Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Sun, 17 May 2026 21:29:23 -0400 Subject: [PATCH 14/73] remove empty docs page boilerplate --- .../packages/Macaulay2Doc/functions/wedgeProduct-doc.m2 | 4 ---- 1 file changed, 4 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2 index 9bdf6183ea6..14c68c4fb4c 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2 @@ -1,7 +1,3 @@ ---- status: TODO ---- author(s): ---- notes: - doc /// Key (wedgeProduct, ZZ, ZZ, Module) From c79b081ae6cdbcb23bb035f11cd0ceb6f9ad6ef0 Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Sun, 17 May 2026 17:30:57 -0400 Subject: [PATCH 15/73] cleanup tensor docs --- .../Macaulay2Doc/functions/tensor-doc.m2 | 58 +++++++++++++------ 1 file changed, 41 insertions(+), 17 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 index c30c056a629..331a5e656a4 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 @@ -2,10 +2,6 @@ --- author(s): --- notes: --- TODO: --- (tensor, Matrix, Matrix) --- (tensor, Module, Module) - L := { (tensor, QuotientRing, QuotientRing), (tensor, PolynomialRing, PolynomialRing), @@ -93,7 +89,7 @@ Node tensor product of the monoids or rings Description Text - This is the same as {\tt A ** B} except that options are allowed, + @TT "tensor(A, B)"@ is the same as {\tt A ** B} except that options are allowed, see @TO (symbol **, Monoid, Monoid)@ and @TO (symbol **, Ring, Ring)@. This method allows many of the options available for monoids, see @TO monoid@ for details. This method essentially combines the variables of {\tt A} and {\tt B} into one monoid or ring. @@ -117,6 +113,14 @@ Node describe (C = tensor(A, B, DegreeRank => 1, Degrees => {5:1})) degreeLength C degreesRing C + Text + You can take tensor powers of a single ring or module. Iterated tensor + products are associated from the right so @TT "R^**3"@ is a synonym for @TT "R ** ( R ** R)"@. + Example + kk = ZZ/101 + R = kk[a, b] + R^**3 + R ** (R ** R) Text Packing monomials into smaller space is more efficient, but less flexible. The default is 32 bits, so if you want to pack them into 8 bit exponents, use: @@ -442,15 +446,35 @@ document { /// } -document { - Key => { - tensorAssociativity, - (tensorAssociativity, Module, Module, Module), - }, - Headline => "associativity isomorphisms for tensor products", - TT "tensorAssociativity(A,B,C)", " -- produces the isomorphism from - A**(B**C) to (A**B)**C.", - PARA{}, - "Currently implemented for modules and chain complexes.", - SeeAlso => {"OldChainComplexes :: ChainComplex", "Module"} -} +doc /// + Key + tensorAssociativity + (tensorAssociativity, Module, Module, Module) + Headline + associativity isomorphisms for tensor products + Usage + tensorAssociativity(A, B, C) + Inputs + A:Module + B:Module + C:Module + Outputs + :Module + A map $A \otimes (B \otimes C) \rightarrow (A \otimes B) \otimes C$. + Description + Text + Produce the isomorphism that exhibits associativity of the tensor product + construction. + Example + kk = ZZ/101 + R = kk[a, b, c] + I = ideal (a, b); A = I/I^2 + J = ideal (b, c); B = J/J^2 + K = ideal (a, c); F = K/K^2 + T = A_0 ** (B_0 ** C_0) + T' = (A_0 ** B_0) ** C_0 + assert(tensorAssociativity(A, B, C) * T == T') + SeeAlso + "OldChainComplexes :: ChainComplex" + Module +/// From b072c6051e9c1175ff9ad863c0045671142ffce5 Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Mon, 18 May 2026 10:33:20 -0400 Subject: [PATCH 16/73] document strategy for primary decomposition --- .../packages/PrimaryDecomposition/doc.m2 | 36 ++++++++++++++----- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 b/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 index c63c64da557..c2d9236b89c 100644 --- a/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 +++ b/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 @@ -117,6 +117,27 @@ Node C = primaryDecomposition I; I == intersect C #C + Text + This function has one optional input @TT "Strategy"@, which accepts three + possible values used to determine the algorithm for finding embedded components. + @UL { + {TT("Res"), " - This strategy is closest to the original Eisenbud-Huneke-Vasconcelos method."}, + {TT "Hom"}, + {TT "Sat"}, + }@ + + If you want to specify the @TT "Strategy"@ to be used by @TO localize@ as well, + this can be specified by passing a @TT "Hybrid"@ Strategy in the form + + @UL { + {TT "Hybrid{primaryDecompisition.Stategy, localize.Strategy}"} + }@ + + While the default (and typically fastest) strategy is @TT "Sat"@, it is recommended to try different + @TT "Strategy"@ values if the computation of a particular embedded component is taking too long. + One can start the computation with one strategy, and interrupt and resume with a different strategy + (even multiple times) if desired. + Text Recall that @TO "Macaulay2Doc :: List / Function"@ applies a function to each element of a list, returning the results as a list. This is often useful with lists of ideals, @@ -131,8 +152,8 @@ Node Example associatedPrimes I / print; Caveat - -- FIXME - The ground ring must be a prime field. + Some strategies require the ground ring to be a prime field but results can + be obtained in some cases even for more general ground rings. SeeAlso (primaryDecomposition, Module) (associatedPrimes, Ideal) @@ -213,15 +234,14 @@ Node known primary components. To display detailed information throughout the computation, set the global variable @TO "debugLevel"@ to a value greater than 0, e.g. @TT "debugLevel=1"@ (or @TT "debugLevel=2"@ for even more detail). - This function has one optional input @TT "Strategy"@, which accepts 3 + This function has one optional input @TT "Strategy"@, which accepts three possible values that determine the algorithm for finding embedded components. --- FIXME @UL { - {TT "Res", PARA {"This strategy is closest to the original Eisenbud-Huneke-Vasconcelos method."}}, - {TT "Hom"}, - {TT "Sat"}, - }@ + {TT("Hybrid{Res}"), " - This strategy is closest to the original Eisenbud-Huneke-Vasconcelos method."}, + {TT "Hybrid{Hom}"}, + {TT "Hybrid{Sat}"}, + }@ While the default (and typically fastest) strategy is @TT "Sat"@, it is recommended to try different @TT "Strategy"@ values if the computation of a particular embedded component is taking too long. From 5fbb8b680f3a602a9a6589273ee8a1e627a53ef4 Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Mon, 18 May 2026 10:42:31 -0400 Subject: [PATCH 17/73] add some examples --- .../packages/PrimaryDecomposition/doc.m2 | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 b/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 index c2d9236b89c..ade010fc9cc 100644 --- a/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 +++ b/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 @@ -132,12 +132,16 @@ Node @UL { {TT "Hybrid{primaryDecompisition.Stategy, localize.Strategy}"} }@ - + Example + kk = ZZ/3 + R = kk[a,b] + I = ideal {a^2, a*b} + primaryDecomposition(I, Strategy => Hybrid{Res, 1}) + Text While the default (and typically fastest) strategy is @TT "Sat"@, it is recommended to try different @TT "Strategy"@ values if the computation of a particular embedded component is taking too long. One can start the computation with one strategy, and interrupt and resume with a different strategy (even multiple times) if desired. - Text Recall that @TO "Macaulay2Doc :: List / Function"@ applies a function to each element of a list, returning the results as a list. This is often useful with lists of ideals, @@ -151,9 +155,14 @@ Node and can be obtained by using @TO (associatedPrimes, Ideal)@. Example associatedPrimes I / print; - Caveat - Some strategies require the ground ring to be a prime field but results can - be obtained in some cases even for more general ground rings. + Text + Some strategies require the ground ring to be a prime field but results can + be obtained in some cases even for more general ground rings. + Example + kk = GF(9) + R = kk[a,b] + I = ideal {a^2, a*b} + primaryDecomposition(I) SeeAlso (primaryDecomposition, Module) (associatedPrimes, Ideal) From 6d5d2872489debb85f8a7a71acd78e5aa45e245d Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Mon, 18 May 2026 10:57:00 -0400 Subject: [PATCH 18/73] spell --- M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 b/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 index ade010fc9cc..5ac2dc8d495 100644 --- a/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 +++ b/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 @@ -130,7 +130,7 @@ Node this can be specified by passing a @TT "Hybrid"@ Strategy in the form @UL { - {TT "Hybrid{primaryDecompisition.Stategy, localize.Strategy}"} + {TT "Hybrid{primaryDecompisition.Strategy, localize.Strategy}"} }@ Example kk = ZZ/3 From 30bbacb860fca498d421595d1781e586f865e981 Mon Sep 17 00:00:00 2001 From: David Eisenbud Date: Sun, 17 May 2026 14:48:19 -0400 Subject: [PATCH 19/73] worked on local rings and primary decomposition --- M2/Macaulay2/packages/LocalRings.m2 | 11 +++- M2/Macaulay2/packages/LocalRings/doc.m2 | 4 -- M2/Macaulay2/packages/PrimaryDecomposition.m2 | 51 ++++++++----------- M2/Macaulay2/packages/Saturation.m2 | 7 ++- M2/Macaulay2/packages/SectionRing.m2 | 43 ++++++++++++++++ 5 files changed, 78 insertions(+), 38 deletions(-) diff --git a/M2/Macaulay2/packages/LocalRings.m2 b/M2/Macaulay2/packages/LocalRings.m2 index dbe7f41bbfb..ea69d7f00fc 100644 --- a/M2/Macaulay2/packages/LocalRings.m2 +++ b/M2/Macaulay2/packages/LocalRings.m2 @@ -49,7 +49,7 @@ exportFrom_Core { "LocalRing" } export { "localRing", "liftUp", - "presentationComplex", -- TODO: what was this for? +-- "presentationComplex", -- TODO: what was this for? "hilbertSamuelFunction", -- Legacy "setMaxIdeal", @@ -63,6 +63,7 @@ export { "maxIdeal" -- not documented } +protect presentationComplex -- << "--------------------------------------------------------------------------------------" << endl; -- << "-- The LocalRings package is experimental, but old methods are still available. --" << endl; -- << "-- See the documentation and comments in the package to learn more. --" << endl; @@ -504,7 +505,13 @@ beginDocumentation() load ("./LocalRings/doc.m2") end-- - +restart +load "LocalRings.m2" +uninstallPackage"LocalRings" +restart +installPackage"LocalRings" +check "LocalRings" +viewHelp LocalRings --==================================== Under Development ====================================-- --TODO: implement a prime filtration diff --git a/M2/Macaulay2/packages/LocalRings/doc.m2 b/M2/Macaulay2/packages/LocalRings/doc.m2 index 6d73b479c92..879049b7359 100644 --- a/M2/Macaulay2/packages/LocalRings/doc.m2 +++ b/M2/Macaulay2/packages/LocalRings/doc.m2 @@ -78,10 +78,6 @@ Node P = ideal(x,y,z,w) setMaxIdeal P -- version 1.0 R = localRing(S, P) -- version 2.0 and above --- TODO --- Text --- @TO localComplement@ --- Example Text Computing syzygies using @TO localsyz@ and @TO syz@: Example diff --git a/M2/Macaulay2/packages/PrimaryDecomposition.m2 b/M2/Macaulay2/packages/PrimaryDecomposition.m2 index a5f3d330937..93741c7fa4e 100644 --- a/M2/Macaulay2/packages/PrimaryDecomposition.m2 +++ b/M2/Macaulay2/packages/PrimaryDecomposition.m2 @@ -519,22 +519,24 @@ topComponents Ideal := Ideal => I -> ( R := ring I; c := codim I; annihilator Ext^c(cokernel generators I, R)) + topComponents Module := Module => M -> ( - R := ring M; - if not isPolynomialRing R or not isAffineRing R then error "expected a polynomial ring"; - c := codim M; - p := pdim M; -- will compute a resolution if needed... - while p > c do ( - E := minimalPresentation Ext^p(M,R); - if E != 0 and codim E === p then ( - -- improve M - J := annihilator E; - I := saturate(M, J); - -- alternate strategy: modify M as well: - -- this next line could be commented out - M = (ambient I)/I); - p = if pdim M < p then pdim M else p-1); - M) + N := 0*M + if not isPolynomialRing R or not isAffineRing R then error "expected a polynomial ring"; + c := codim M; + p := pdim M; -- will compute a resolution if needed... + while p > c do ( + E := minimalPresentation Ext^p(M,R^1); + if E != 0 and codim E === p then ( + -- improve M + J := annihilator E; + N = saturate(N, J)); + -- alternate strategy: modify M as well: + -- this next line could be commented out + -- M = (ambient I)/I); + p = p-1); + M/N) + topComponents(Module, ZZ) := Module => (M, e) -> ( S := ring M; N := 0 * M; @@ -545,20 +547,9 @@ topComponents(Module, ZZ) := Module => (M, e) -> ( if debugLevel > 0 then printerr("Getting annihilator of Ext..."); I := annihilator E; if debugLevel > 0 then printerr("Removing components of codim " | toString(f)); - N = N : I); + N = saturate(N, I); f = f-1); - N) - --- This used to be commented out in modules2.m2 --- if it isn't useful anymore, delete it ---topComponents Module := M -> ( --- R := ring M; --- c := codim M; --- annihilator minimalPresentation Ext^c(M, R)) ---document { topComponents, --- TT "topComponents M", "produce the annihilator of Ext^c(M, R), where c --- is the codimension of the support of the module M." --- } + M/N) --------------------------- -- removeLowestDimension -- @@ -575,9 +566,9 @@ removeLowestDimension Module := Module => M -> ( p := pdim M; -- now loop (starting at p) trying to find the largest -- d such that codim Ext^d(M,R) == d - while p > c and codim (E = Ext^p(M, R)) > p do p = p-1; - if p == c then ambient M -- M is C.M. and unmixed, so return (1) + if p == c then return coker matrix{{1_R}}; --M is pure-dimensional. else ( -- use the annihilator of Ext to improve M + E := Ext^d(M,R); J := annihilator E; cokernel generators saturate(image presentation M, J)) ) diff --git a/M2/Macaulay2/packages/Saturation.m2 b/M2/Macaulay2/packages/Saturation.m2 index 7cd9c8c1a16..9fbcfe170fb 100644 --- a/M2/Macaulay2/packages/Saturation.m2 +++ b/M2/Macaulay2/packages/Saturation.m2 @@ -143,10 +143,10 @@ updateComputation(QuotientComputation, Thing) := Thing => options quotient >> op --quotient = method(...) -- defined in m2/quotient.m2 quotient(Ideal, Ideal) := Ideal => opts -> (I, J) -> quotientHelper(I, J, (quotient, Ideal, Ideal), opts) -quotient(Ideal, Number) := +quotient(Ideal, Number) := Ideal => opts -> (I, f) -> quotient(I, ideal f, opts) quotient(Ideal, RingElement) := Ideal => opts -> (I, f) -> quotient(I, ideal f, opts) Ideal : Ideal := Ideal => (I, J) -> quotient(I, J) -Ideal : Number := +Ideal : Number := Ideal Ideal : RingElement := Ideal => (I, f) -> quotient(I, f) -- TODO: why is this the right thing to do? @@ -901,3 +901,6 @@ elapsedTime saturate(J, I, Strategy => Eliminate); degree I elapsedTime(J : I_0); + + + diff --git a/M2/Macaulay2/packages/SectionRing.m2 b/M2/Macaulay2/packages/SectionRing.m2 index d6401d10db4..39e8ba35c06 100644 --- a/M2/Macaulay2/packages/SectionRing.m2 +++ b/M2/Macaulay2/packages/SectionRing.m2 @@ -472,6 +472,49 @@ doc /// /// +doc /// + Key + convertScalarVect + Headline + substitute a list of ring elements into a target ring + Usage + convertScalarVect(S, L) + Inputs + S:Ring + the target ring + L:List + a list of ring elements + Outputs + :List + a list with elements substituted into the target ring + Description + Text + convertScalarVect is a helper function used internally by the SectionRing package to convert + scalar vector entries from one ring to another. Specifically, it takes a list L of elements + from an ambient ring and applies the substitution map into the target ring S, returning a + new list with the substituted elements. + + This function is applied when processing the kernel of a matrix in the computation of the + section ring of a Weil divisor. When a scalar vector is detected in the kernel of the + matrix MapTot (using isVectScalar), its entries are converted to live in the quotient ring S + so they can be used to generate relations in the section ring. + + Text + The substitution is performed using Macaulay2's @TO sub@ function, which maps each element + z in the input list L to sub(z, S) in the target ring. This operation is essential for + maintaining consistency of ring elements during the iterative computation of section rings. + + Example + R = QQ[x,y]; + S = QQ[a,b,c]; + L = {x+y, x-y}; + convertScalarVect(S, L) + + Text + Note that convertScalarVect is typically not called directly by users; it is used internally + by the sectionRing function as part of the algorithm for computing relations in the section ring. +/// + TEST /// R = QQ[x,y,z]/ideal(x^3+y^3-z^3); I = ideal(x,y-z); From e68a0271f0b935aefbf5d3727813adbbd356be83 Mon Sep 17 00:00:00 2001 From: David Eisenbud Date: Mon, 18 May 2026 10:08:12 -0400 Subject: [PATCH 20/73] fixes --- M2/Macaulay2/packages/PrimaryDecomposition.m2 | 12 ++++++------ M2/Macaulay2/packages/Saturation.m2 | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/M2/Macaulay2/packages/PrimaryDecomposition.m2 b/M2/Macaulay2/packages/PrimaryDecomposition.m2 index 93741c7fa4e..cb14a608d05 100644 --- a/M2/Macaulay2/packages/PrimaryDecomposition.m2 +++ b/M2/Macaulay2/packages/PrimaryDecomposition.m2 @@ -521,8 +521,9 @@ topComponents Ideal := Ideal => I -> ( annihilator Ext^c(cokernel generators I, R)) topComponents Module := Module => M -> ( - N := 0*M - if not isPolynomialRing R or not isAffineRing R then error "expected a polynomial ring"; + N := 0*M; + R := ring M; + if not isPolynomialRing R or not isAffineRing R then error "expected a polynomial ring"; c := codim M; p := pdim M; -- will compute a resolution if needed... while p > c do ( @@ -547,7 +548,7 @@ topComponents(Module, ZZ) := Module => (M, e) -> ( if debugLevel > 0 then printerr("Getting annihilator of Ext..."); I := annihilator E; if debugLevel > 0 then printerr("Removing components of codim " | toString(f)); - N = saturate(N, I); + N = saturate(N, I)); f = f-1); M/N) @@ -560,15 +561,14 @@ topComponents(Module, ZZ) := Module => (M, e) -> ( --removeLowestDimension = method() removeLowestDimension Module := Module => M -> ( -- only works for polynomial rings... - local E; R := ring M; c := codim M; p := pdim M; -- now loop (starting at p) trying to find the largest -- d such that codim Ext^d(M,R) == d - if p == c then return coker matrix{{1_R}}; --M is pure-dimensional. + if p == c then return coker matrix{{1_R}} --M is pure-dimensional. else ( -- use the annihilator of Ext to improve M - E := Ext^d(M,R); + E := Ext^p(M,R); J := annihilator E; cokernel generators saturate(image presentation M, J)) ) diff --git a/M2/Macaulay2/packages/Saturation.m2 b/M2/Macaulay2/packages/Saturation.m2 index 9fbcfe170fb..cc129236b0f 100644 --- a/M2/Macaulay2/packages/Saturation.m2 +++ b/M2/Macaulay2/packages/Saturation.m2 @@ -146,7 +146,7 @@ quotient(Ideal, Ideal) := Ideal => opts -> (I, J) -> quotientHelper(I, J quotient(Ideal, Number) := Ideal => opts -> (I, f) -> quotient(I, ideal f, opts) quotient(Ideal, RingElement) := Ideal => opts -> (I, f) -> quotient(I, ideal f, opts) Ideal : Ideal := Ideal => (I, J) -> quotient(I, J) -Ideal : Number := Ideal +Ideal : Number := Ideal => opts -> (I, f) -> quotient(I, ideal f, opts) Ideal : RingElement := Ideal => (I, f) -> quotient(I, f) -- TODO: why is this the right thing to do? From 72337905e82b27cbba8e1e8111a13afd53fcd781 Mon Sep 17 00:00:00 2001 From: klee669 Date: Sun, 17 May 2026 17:19:18 -0400 Subject: [PATCH 21/73] Add Numerical algebraic geometry tutorial (incomplete) Add a new tutorial file M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 covering homotopy continuation, witness sets, and examples using the NumericalAlgebraicGeometry package. Register the tutorial in loads.m2 and add it to the top-level navigation in ov_top.m2. --- M2/Macaulay2/packages/Macaulay2Doc/loads.m2 | 4 + M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 | 3 +- M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 | 86 ++++++++++++++++++++ 3 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 diff --git a/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 b/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 index 285dbdb7320..9cb8d76171a 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 @@ -94,3 +94,7 @@ document { Key => "Tutorial: Fano varieties", ld "tu_Fano.m2" } +document { + Key => "Tutorial: Numerical algebraic geometry", + ld "tu_NAG.m2" + } diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 index cfcd006ce94..47f23518b5b 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 @@ -46,6 +46,7 @@ Node > "Tutorial: Canonical Embeddings of Plane Curves and Gonality" > "Tutorial: Fano varieties" > "Tutorial: Divisors" + > "Tutorial: Numerical algebraic geometry" :Mathematical Computations > "elementary arithmetic" > "commutative algebra" @@ -89,7 +90,7 @@ Node - Boyana Martinova - Eliana Duarte - Lars Kastner - - Kinsun Lee + - Kisun Lee -- the following contributors don't appear in git history -- but have been credited in various documentation files. - Sorin Popescu diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 b/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 new file mode 100644 index 00000000000..edb843c7e60 --- /dev/null +++ b/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 @@ -0,0 +1,86 @@ +-- {\it Numerical algebraic geometry} uses techniques from numerical analysis +-- to study and approximate solutions of systems of polynomial equations. +-- +-- Traditionally, polynomial systems are studied using symbolic methods +-- such as Gr\"obner bases, resultants, and elimination techniques. +-- While these methods are powerful, they often become prohibitively slow +-- for large or complicated systems. +-- Numerical algebraic geometry provides an alternative by replacing exact symbolic computations +-- with high-precision numerical approximations. + + + +----------------------------------------------- +-- A. Homotopy continuation +----------------------------------------------- +-- The central tool in numerical algebraic geometry is {\it homotopy continuation}. +-- This method constructs a homotopy between two polynomial systems +-- and tracks solutions from one system to the other. +-- +-- Typically, one system is chosen so that its solutions are already known +-- or easy to compute; the {\it start system}. +-- The other system is the polynomial system of interest, called the {\it target system}. +-- +-- One common constructions is the {\it straight-line homotopy}. +-- Given a target system $f$ and a start system $g$, the homotopy is defined by +-- $H(x,t) = (1-t)g(x) + tf(x)$. +-- Starting from a known solution $x^*$ of $g$ at $t=0$, +-- it tracks the solution path as $t$ moves toward $1$, +-- approximating a solution of $f$. +-- +-- The package {\tt NumericalAlgebraicGeometry} provides fundamental tools +-- in numerical algebraic geometry. + +--^ +needsPackage "NumericalAlgebraicGeometry" +--$ + +R = CC[x,y] +g = {x^2-1,y^2-1} +f = {x^2+y^2-1, (x-y)^2-1} +solsS = {(1,-1),(1,1),(-1,1),(-1,-1)} +track(g,f,solsS) + +-- In this example, the start system is a {\it B\'ezout start system}. +-- giving a total number of paths equal to the product of the degrees +-- of the defining polynomials. This number is an upper bound +-- for the number of isolated solutions of the target system. + +-- The same computation can also be simply carried out using: +--^ +R = CC[x,y]; +--$ + +f = {x^2+y^2-1, (x-y)^2-1}; +solveSystem f + + +----------------------------------------------- +-- B. Witness sets and numerical irreducible decomposition +----------------------------------------------- +-- The idea of homotopy continuation for finding a solution to zero-dimensional systems +-- extends to the study positive-dimensional varieties. +-- The key observation is that intersecting a positive-dimensional variety +-- with codimension-many generic linear slices produces a zero-dimensional variety. +-- +-- The data consisting of a polynomial system, a collection of generic linear slices, +-- and the resulting finite set of points is called a {\it witness set}. +-- Witness sets provide a numerical representation of +-- positive-dimensional algebraic varieties and can be used to compute: +-- +-- 1. dimension +-- +-- 2. degree +-- +-- 3. sampling from a variety +-- +-- 4. irreducible decomposition of a variety +-- +-- This computation can be carried out using: +--^ +R = CC[x,y,z]; +--$ + +I = ideal {(x^2+y^2+z^2-1)*(y-x^2), (x^2+y^2+z^2-1)*(z-x^3)}; +W = components numericalIrreducibleDecomposition I -- the variety consists of two components +sample first W -- sampling a random point on the first component From adcb335dc94e1667352fe5a8393d68c9a3534be5 Mon Sep 17 00:00:00 2001 From: David Eisenbud Date: Mon, 18 May 2026 11:10:58 -0400 Subject: [PATCH 22/73] fixing the files docs --- M2/Macaulay2/packages/Macaulay2Doc/ov_files.m2 | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_files.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_files.m2 index 311a6b075a6..e41e16ce81a 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_files.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_files.m2 @@ -1,10 +1,11 @@ -- Copyright 1993-1998 by Daniel R. Grayson document { - Key => File, + Key => "File", Headline => "the class of all files", + "For ordinary printing to a file see ", TO "file" , " .", "Files may be input files, output files, pipes, or sockets. - A list of currently open files may be obtained with ", TO "openFiles", ".", + A list of currently open files may be obtained with ", TO "openFiles", ".", } document { @@ -62,10 +63,10 @@ document { } document { - Key => { "printing to a file", (symbol <<, File, Thing),(symbol <<, String, Thing), (symbol <<, File, Manipulator), + Key => {"file", (symbol <<, File, Thing),(symbol <<, String, Thing), (symbol <<, File, Manipulator), (symbol <<, Nothing, Thing),(symbol <<, Nothing, Manipulator), (symbol <<, Thing), (symbol <<, File, Symbol),(symbol <<, File, Net),(symbol <<,File,String) }, - Headline => "print to a file", + Headline => "print to, or read from a file", Usage => "f << x\n << x", Inputs => { "f" => Nothing => { ofClass {File, String, Nothing} }, @@ -86,6 +87,10 @@ document { PARA { "Parsing of ", TO "<<", " associates leftward, so that several objects may be displayed with an expression such as ", TT "f< { endl, flush, close }, + SeeAlso => { endl, flush, close, removeFile, Database }, Subnodes => { TO printString, TO stdio, From 2a9252fa7dc5e4009a668fb21d1c06c8f8b25841 Mon Sep 17 00:00:00 2001 From: David Eisenbud Date: Mon, 18 May 2026 13:41:20 -0400 Subject: [PATCH 23/73] doc for kernel --- .../Macaulay2Doc/functions/kernel-doc.m2 | 39 +++++++++++++------ .../packages/Macaulay2Doc/ov_files.m2 | 2 +- 2 files changed, 28 insertions(+), 13 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 index 11a850045f1..675a84e84b7 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 @@ -13,9 +13,16 @@ Node Key kernel Headline - kernel of a map + kernel of a map of modules or rings + Description + Text + See the separate documentation nodes for the two cases. To compute + the kernel of a map of free modules the command @TO syz@ is usually faster, + since it computes only the generators of the kernel, not the relations on them, + as is necessary to return the kernel as a module. SeeAlso source + syz /// document { @@ -48,27 +55,35 @@ document { document { Key => {(kernel,Matrix), (kernel, RingElement)}, - Headline => "kernel of a matrix", - Usage => "kernel f", + Headline => "kernel of a map of modules", + Usage => "kernel f, kernel a", Inputs => { "f" => {"a map of modules ", TT "M --> N"} }, Outputs => { Module => {"the kernel of f, a submodule of M"} }, - "If f is ", ofClass RingElement, ", then it will be interpreted as a one by one matrix.", PARA{}, - "The kernel is the submodule of M of all elements mapping to zero under ", TT "f", ". - Over polynomial rings, this is computed using a Gröbner basis computation.", + "The kernel is the submodule of M of all elements mapping to zero under ", TT "f", ".", + "If f is a RingElement it is interpreted as a 1 by 1 matrix",".", EXAMPLE lines /// - R = ZZ/32003[vars(0..10)] - M = genericSkewMatrix(R,a,5) - ker M + R = ZZ/32003[a,b]/(ideal(a,b))^3 + M = R^1/(ideal a^2) + mat = matrix{{a^2,b^2},{b,a}} + ker mat + presentation ker mat + syz mat + f = map(M++M, M++M, mat) + ker f ///, SeeAlso => {syz, - -- Mike wanted this: "kernel, cokernel and image of a map of modules", - genericSkewMatrix} - } + cokernel, + image, + map, + matrix + } + } + document { Key => [kernel, SubringLimit], diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_files.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_files.m2 index e41e16ce81a..8207d416a48 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_files.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_files.m2 @@ -107,7 +107,7 @@ document { value get fn removeFile fn ///, - SeeAlso => { endl, flush, close, removeFile, Database }, + SeeAlso => { endl, flush, close, removeFile, Database, File }, Subnodes => { TO printString, TO stdio, From 2105e9433e644a95e2fef663c4d68fc39f62daee Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 14:09:38 -0400 Subject: [PATCH 24/73] Refresh commutative algebra teaching materials entry --- .../packages/Macaulay2Doc/ov_examples.m2 | 19 ++++++++----------- M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 | 2 +- .../packages/Macaulay2Doc/tu_elementary1.m2 | 5 +++++ 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 index 57c13958e5e..0d36c7d61e5 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 @@ -96,7 +96,7 @@ Node :Tutorials > "Tutorial: Modules in Macaulay2" > "Tutorial: Elementary uses of Gröbner bases" - > @TO2("A first course in commutative algebra", "teaching materials")@ + > "Teaching Materials" :Selected Packages > @TOH "IntegralClosure :: IntegralClosure"@ > @TOH "PrimaryDecomposition :: PrimaryDecomposition"@ @@ -431,18 +431,15 @@ Node /// document { - Key => "A first course in commutative algebra", - "This section includes tutorials showing how to do - basic commutative algebra constructions in Macaulay2. - This section is being written by Mike Stillman, for use - with his Fall 2005 course: Math 634, Commutative algebra, - at Cornell University. This course covers basic commutative - algebra, at the level of Atiyah-Macdonald, and Greuel-Pfister.", + Key => {"Teaching Materials", "A first course in commutative algebra"}, + "This section collects teaching materials and introductory tutorials + for basic commutative algebra in Macaulay2, at roughly the level of + Atiyah-Macdonald and Greuel-Pfister.", PARA{}, - "Macaulay2 examples corresponding to the Singular examples in the - book by Greuel-Pfister may also be found here.", + "Macaulay2 examples corresponding to examples in the Greuel-Pfister + text may also be found here.", Subnodes => { - TO "Elementary uses of Groebner bases I. Math 634 Fall 2005", + TO2("Elementary uses of Groebner bases I. Math 634 Fall 2005", "Elementary uses of Groebner bases"), TO "M2SingularBook" } } diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 index e19745c1364..e1586c675fe 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 @@ -35,13 +35,13 @@ Node :Mathematical Tutorials -- These tutorials begin with broader introductions and continue with -- more specialized worked examples in algebra and geometry. - > "A first course in commutative algebra" > "Tutorial: Modules in Macaulay2" > "Tutorial: Elementary uses of Gröbner bases" > "Tutorial: Divisors" > "Tutorial: Canonical Embeddings of Plane Curves and Gonality" > "Tutorial: Fano varieties" > "Tutorial: Numerical algebraic geometry" + > "Teaching Materials" :Mathematical Objects > "rings" > "ideals" diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_elementary1.m2 b/M2/Macaulay2/packages/Macaulay2Doc/tu_elementary1.m2 index 4be38fa733a..dfba7037242 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/tu_elementary1.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/tu_elementary1.m2 @@ -1,3 +1,8 @@ +-- These materials were created by Mike Stillman for his Fall 2005 +-- course Math 634, Commutative Algebra, at Cornell University. +-- The course covered basic commutative algebra at the level of +-- Atiyah-Macdonald and Greuel-Pfister. +-- -- In this tutorial we introduce a number of basic operations -- using Gröbner bases, and at the same time become familiar -- with a range of useful Macaulay2 constructs. From c131b3312d6bd24310f144e1b72fcba63ea8ec52 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 14:13:31 -0400 Subject: [PATCH 25/73] Refresh commutative algebra tutorial load entry --- M2/Macaulay2/packages/Macaulay2Doc/loads.m2 | 2 +- M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 b/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 index 5157cf1acd3..737bf2a5ee7 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 @@ -87,7 +87,7 @@ document { ld "tu_divisors.m2" } document { - Key => "Elementary uses of Groebner bases I. Math 634 Fall 2005", + Key => {"Elementary uses of Groebner bases I", "Elementary uses of Groebner bases I. Math 634 Fall 2005"}, ld "tu_elementary1.m2" } document { diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 index 0d36c7d61e5..666971f086a 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 @@ -439,7 +439,7 @@ document { "Macaulay2 examples corresponding to examples in the Greuel-Pfister text may also be found here.", Subnodes => { - TO2("Elementary uses of Groebner bases I. Math 634 Fall 2005", "Elementary uses of Groebner bases"), + TO2("Elementary uses of Groebner bases I", "Elementary uses of Groebner bases"), TO "M2SingularBook" } } From 1bffde7315a4af720c95948c9f16831bd48c6c15 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 14:34:14 -0400 Subject: [PATCH 26/73] Fix tensorAssociativity documentation example --- M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 index 331a5e656a4..be71b6f811b 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 @@ -470,7 +470,7 @@ doc /// R = kk[a, b, c] I = ideal (a, b); A = I/I^2 J = ideal (b, c); B = J/J^2 - K = ideal (a, c); F = K/K^2 + K = ideal (a, c); C = K/K^2 T = A_0 ** (B_0 ** C_0) T' = (A_0 ** B_0) ** C_0 assert(tensorAssociativity(A, B, C) * T == T') From 37fdc70b923dc7724a501758c67321edd0d2cf10 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 15:45:51 -0400 Subject: [PATCH 27/73] Improve concept-to-command documentation guidance --- .../packages/Macaulay2Doc/ov_examples.m2 | 5 +++++ .../packages/Macaulay2Doc/ov_first_session.m2 | 9 +++++++++ .../Macaulay2Doc/ov_getting_started.m2 | 18 ++++++++++++++++++ M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 | 12 ++++++++---- 4 files changed, 40 insertions(+), 4 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 index 666971f086a..10ae4b047bf 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 @@ -436,6 +436,11 @@ document { for basic commutative algebra in Macaulay2, at roughly the level of Atiyah-Macdonald and Greuel-Pfister.", PARA{}, + "Use these materials when you want worked examples that connect + commutative-algebra topics to first Macaulay2 commands, including + Gröbner bases, ideals and modules, Hilbert invariants, elimination, + and resolutions.", + PARA{}, "Macaulay2 examples corresponding to examples in the Greuel-Pfister text may also be found here.", Subnodes => { diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_first_session.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_first_session.m2 index a04b24a9613..1df4aba542b 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_first_session.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_first_session.m2 @@ -286,6 +286,15 @@ Node We can use @TO betti@ to see the degrees involved in the Gröbner basis. Example betti gb j + Text + This first session has touched the commands most users need when translating + a basic algebra problem into Macaulay2: create a @TO2("rings", "ring")@, build an + @TO "ideal"@ or @TO matrix@, form modules with @TO kernel@, @TO cokernel@, + and @TO image@, compute a resolution with @TO "OldChainComplexes :: resolution"@, + compute a Gröbner basis with @TO gb@, and inspect answers with + @TO generators@ and @TO betti@. For more examples organized by subject, + return to the front page sections on mathematical objects, mathematical + computations, and tutorials. Text To exit your first session, you can type @KBD "exit"@ or @KBD "quit"@. SeeAlso diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_getting_started.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_getting_started.m2 index 24b9cf589e1..a16537fe88f 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_getting_started.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_getting_started.m2 @@ -20,6 +20,9 @@ Node Once Macaulay2 is installed on your system, use the information here to set up the Emacs interface (the recommended way to run Macaulay2), bookmark the html documentation, and start your first Macaulay2 session. + After installation, the usual path is to try @TO "a first Macaulay2 session"@, + learn how to search with @TO "reading the documentation"@, and then choose + a tutorial or computation page matching the mathematical problem you want to solve. Text @HEADER2 "Checking your installation"@ @@ -87,6 +90,10 @@ Node for other popular editors that at least support syntax highlighting for Macaulay2 files. Once you are set up, it is time for @TO "a first Macaulay2 session"@. + After that first tour, the front page sections on mathematical objects, + mathematical computations, and packages are the main paths from a goal + such as constructing an ideal, computing a Gröbner basis, finding a resolution, + or loading a specialized package to the corresponding command. Node Key @@ -341,6 +348,17 @@ Node :Getting other information from documentation > examples + Text + When you know the mathematical goal but not the command name, start with + @TO "about"@ for topic searches, @TO "apropos"@ for command-name searches, + and @TO "headlines"@ to scan the matching commands with their short descriptions. + For example, Hilbert invariants are usually found by searching for + @KBD "hilbert"@, Gröbner-basis commands by searching for @KBD "gb"@ or + @KBD "Groebner"@, and package-level tools by browsing + @TO2("packages provided with Macaulay2", "packages by subject area")@. + Once you find a promising command, use @TO "help"@ or @TO "viewHelp"@ to + read its documentation and @TO "examples"@ to extract its example code. + Text To begin, the @TO "about"@ method allows for searching all documentation nodes whose title or content contains a given string: diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 index e1586c675fe..5d0beebfde7 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 @@ -15,10 +15,14 @@ Node This documentation includes getting-started guides, language and reference material, tutorials, and package documentation for the packages distributed with Macaulay2. Text - If you are new to Macaulay2, start with the setup notes and a first Macaulay2 - session. If you know the mathematics you want to do but not yet the command or - package name, browse the sections on practical guides, mathematical objects, - computations, and packages. + If you are new to Macaulay2, start with @TO "setting up Macaulay2"@, + @TO "a first Macaulay2 session"@, and @TO "reading the documentation"@. + If you know the mathematical object or computation you want, use the + Mathematical Objects and Mathematical Computations sections below to move + from concepts such as rings, ideals, matrices, modules, Gröbner bases, + Hilbert functions, and resolutions to the corresponding commands and examples. + For package-level tools, start with @TO2("packages", "loading and using packages")@ + or @TO2("packages provided with Macaulay2", "browsing packages by subject area")@. Tree :Getting Started > "setting up Macaulay2" From 99efd0c82c215c6f6208f5b1e509a87f9714c024 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 16:50:09 -0400 Subject: [PATCH 28/73] Fix Macaulay2Doc targeted install blockers --- .../packages/Macaulay2Doc/ov_debugging.m2 | 60 +++++++++++++++---- .../packages/Macaulay2Doc/ov_system.m2 | 2 +- 2 files changed, 50 insertions(+), 12 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 index 8d46c297d8c..062f6b27a9a 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 @@ -195,17 +195,55 @@ document { "One useful way to debug code suspected of being in error is to insert an explicit error message, such as ", TT ///error "debug me"///, ", and start stepping from there, as in the following demonstration." }, - EXAMPLE lines /// - load "Macaulay2Doc/demos/demo2.m2" - code f - f 0 - return - current - disassemble oo - step(-3) - step - step - t + EXAMPLE PRE /// +i1 : load "Macaulay2Doc/demos/demo2.m2" + +i2 : code f + +o2 = .../Macaulay2Doc/demos/demo2.m2:6:4-12:6 + : --source code: + f = t -> ( + x := 1; + error "debug me"; + y := t+1; + z := 1/t; + w := x+t; + ) + +i3 : f 0 +.../Macaulay2Doc/demos/demo2.m2:8:10:(3):[1]: error: debug me +.../Macaulay2Doc/demos/demo2.m2:8:10:(3): entering debugger + +ii4 : return +.../Macaulay2Doc/demos/demo2.m2:9:11:(3):[1]: --stepping limit reached +.../Macaulay2Doc/demos/demo2.m2:9:11:(3): entering debugger + +ii5 : current + +oo5 = local-assign 2 0 2-OP + local-fetch 0 0 + 1 + +oo5 : PseudocodeClosure + +ii6 : disassemble oo + +oo6 = (local-assign 2 0 (2-OP + (local-fetch 0 0) 1)) + +ii7 : step(-3) +.../Macaulay2Doc/demos/demo2.m2:9:11:(3):[1]: --evaluating: (local-assign 2 0 (2-OP + (local-fetch 0 0) 1)) +.../Macaulay2Doc/demos/demo2.m2:9:11:(3):[1]: --evaluating: (2-OP + (local-fetch 0 0) 1) +.../Macaulay2Doc/demos/demo2.m2:9:10:(3):[1]: --evaluating: (local-fetch 0 0) +.../Macaulay2Doc/demos/demo2.m2:9:12:(3):[1]: --stepping limit reached + +ii8 : step +.../Macaulay2Doc/demos/demo2.m2:10:11:(3):[1]: --stepping limit reached + +ii9 : step +.../Macaulay2Doc/demos/demo2.m2:10:11:(3):[1]: error: division by zero + +ii10 : t + +oo10 = 0 ///, SeeAlso => { "debugging" } } diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_system.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_system.m2 index 2d31720a12b..51e45d9075a 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_system.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_system.m2 @@ -32,7 +32,7 @@ document { Subnodes => { "Input and output:", TO "printing to the screen", - TO "printing to a file", + TO2("file", "printing to a file"), TO "reading files", TO "getting input from the user", TO "creating and writing files", From 8183814d2b4870a1c6cd043d359b3430532448c5 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 17:02:35 -0400 Subject: [PATCH 29/73] Reorganize core algebra documentation navigation --- .../Macaulay2Doc/ov_groebner_bases.m2 | 39 +++++++- .../packages/Macaulay2Doc/ov_modules.m2 | 88 ++++++++++++------- .../packages/Macaulay2Doc/ov_ringmaps.m2 | 40 ++++++++- 3 files changed, 129 insertions(+), 38 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_groebner_bases.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_groebner_bases.m2 index edd496c93ea..21f9b2dc2af 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_groebner_bases.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_groebner_bases.m2 @@ -15,6 +15,15 @@ document { "See ", TO GroebnerBasis, " for additional common operations and a comprehensive list of all routines in Macaulay2 which either take Gröbner bases as arguments, or return one.", PARA{}, + "Common Gröbner-basis tasks are routed as follows.", + UL { + {"To compute a Gröbner basis and extract its generators, use ", TO gb, " and ", TO generators, "."}, + {"To inspect leading terms or coefficients, use ", TO leadTerm, ", ", TO leadMonomial, ", and ", TO leadCoefficient, "."}, + {"To reduce modulo an ideal or test normal forms, see ", TO "normal forms", " and ", TO (symbol %, RingElement, Ideal), "."}, + {"To eliminate variables or find implicit equations, see ", TO "elimination of variables", ", ", TO "Elimination::eliminate", ", ", TO selectInSubring, ", and ", TO (kernel, RingMap), "."}, + {"To control a slow or partial computation, see ", TO "fine control of a Groebner basis computation", ", ", TO gbSnapshot, ", ", TO "gbTrace", ", and ", TO forceGB, "."} + }, + PARA{}, "In Macaulay2, Gröbner bases may be computed for ideals and submodules over the following rings:", UL { @@ -119,6 +128,11 @@ document { document { Key => "normal forms", Headline => "compute normal forms with Gröbner bases", + "Use normal forms when you want to reduce an element modulo an ideal, + compare two expressions modulo an ideal, or test membership by checking + whether the remainder is zero. In Macaulay2 the operator ", TO (symbol %, RingElement, Ideal), + " computes this remainder using a Gröbner basis.", + PARA{}, TEX ///Let $R = k[x_1, ..., x_n]$ be a polynomial ring over a field k, and let $I \subset{} R$ be an ideal. Let $\{g_1, ..., g_t\}$ be a Gröbner basis for $I$. For any $f \in{} R$, there is a unique `remainder' $r \in{} R$ such @@ -144,6 +158,12 @@ document { document { Key => "elimination of variables", Headline => "eliminate variables with Gröbner bases", + "Use elimination when you want equations involving only selected variables, + for example to eliminate parameters from a parametrization. The main + approaches are to use an elimination monomial order with ", TO selectInSubring, + ", call ", TO "Elimination::eliminate", ", or construct a ring map and + compute its ", TO (kernel, RingMap), ".", + PARA{}, TEX "Let's consider the problem of finding the polynomial relation of the three polynomials $x = s^3+st+1$, $y = t^3+3t^2+t$, and $z = st^3$. The first method we use is to compute a Gröbner basis using an elimination @@ -226,6 +246,10 @@ document { will then describe Gröbner bases of submodules, and over more general rings.", PARA{}, + "For computation, use ", TO gb, "; for the basis elements, use ", TO generators, + " on the resulting Gröbner basis. Normal forms and elimination are common + applications of the same computation.", + PARA{}, TEX ///Let $R = k[x_1, ..., x_n]$ be a polynomial ring over a field $k$, and let $I \subset R$ be an ideal. A {\it monomial order} on $R$ is a total order, $>$, on the monomials of $R$, which satisfies two @@ -269,8 +293,10 @@ document { document { Key => "computing Groebner bases", - "Gröbner bases are computed with the ", TT "gb", " command; see ", - TO "gb", ". It returns an object of class ", TT "GroebnerBasis", ".", + "Use this page when you want to run a Gröbner-basis computation directly, + extract the computed basis, or stop after a partial computation. Gröbner + bases are computed with the ", TT "gb", " command; see ", TO "gb", + ". It returns an object of class ", TT "GroebnerBasis", ".", EXAMPLE { "R = ZZ/1277[x,y];", "I = ideal(x^3 - 2*x*y, x^2*y - 2*y^2 + x);", @@ -467,8 +493,13 @@ document { document { Key => "fine control of a Groebner basis computation", - "Sometimes a Gröbner basis computation doesn't finish quickly enough. If so - then this section might be of use. THIS PAGE IS UNDER CONSTRUCTION.", + "Use this page when a Gröbner basis computation is too slow, too large, + or needs to be inspected before it finishes. The main controls are the + options ", TO "DegreeLimit", ", ", TO "PairLimit", ", ", + TO "BasisElementLimit", ", ", TO "CodimensionLimit", ", and ", + TO "SubringLimit", "; the inspection tools ", TO gbSnapshot, " and ", + TO "gbTrace", "; and ", TO forceGB, " for creating a Gröbner basis object + from data already known to be a basis.", SUBSECTION "Partially computed Gröbner bases", "Suppose that you have computed part of a Gröbner basis. For diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 index 9857150a007..7e9d6216690 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 @@ -7,28 +7,35 @@ document { PARA{}, "See ", TO "Tutorial: Modules in Macaulay2", " for an overview tutorial on modules.", PARA{}, + "Common module tasks usually start with one of the following pages or commands.", + UL { + {"To create free modules, submodules, quotients, and subquotients, see ", TO "free modules", ", ", TO module, ", ", TO "submodules and quotients", ", and ", TO "subquotient modules", "."}, + {"To move between matrices and modules, use ", TO "matrices to and from modules", ", ", TO kernel, ", ", TO image, ", ", TO cokernel, ", ", TO generators, ", ", TO relations, ", and ", TO presentation, "."}, + {"To construct or inspect maps between modules, start with ", TO "module homomorphisms", ", ", TO "maps between modules", ", ", TO "constructing maps between modules", ", ", TO source, ", ", TO target, ", and ", TO isWellDefined, "."}, + {"To compute syzygies, resolutions, and graded invariants, see ", TO "computing syzygies", ", ", TO syz, ", ", TO "OldChainComplexes :: resolution", ", ", TO betti, ", and ", TO "Hilbert functions and free resolutions", "."} + }, + PARA{}, "For additional common operations and a comprehensive list of all routines in Macaulay2 which return or use modules, see ", TO Module, ".", Subnodes => { TO Module, TO module, TO isModule, - "construction of modules", + "creating modules", TO "free modules", - TO "matrices to and from modules", TO "making modules from matrices", TO "submodules and quotients", TO "subquotient modules", - "properties of modules", + "matrices, kernels, images, and presentations", + TO "matrices to and from modules", + TO "kernel, cokernel and image of a map of modules", TO "manipulating modules", - TO "computing syzygies", TO "extracting elements", TO "minimal presentations and generators", TO "equality and containment of modules", - "homomorphisms (maps) between modules", - -- TODO: combine these + "maps between modules", TO "module homomorphisms", TO "maps between modules", TO "information about a map of modules", @@ -43,7 +50,8 @@ document { -- Mike wanted this: TO "annihilators and submodule quotients", TO "Saturation :: module quotients, saturation, and annihilator", - "graded modules", + "syzygies, resolutions, and graded invariants", + TO "computing syzygies", TO gradedModule, TO "Hilbert functions and free resolutions", -- Mike wanted this: TO "degrees of elements and free modules", @@ -382,6 +390,11 @@ document { document { Key => "module homomorphisms", + "Start here when you have two modules and want to describe a homomorphism + between them. The basic command is ", TO map, "; after construction use + ", TO source, ", ", TO target, ", ", TO matrix, ", and ", TO isWellDefined, + " to inspect the result.", + PARA{}, "A homomorphism ", TT "f : M --> N", " is represented as a matrix from the generators of M to the generators of N.", EXAMPLE { @@ -471,21 +484,16 @@ document { document { -- old?? Key => "constructing maps between modules", - "Let's start with a free module.", - EXAMPLE { - "R = ZZ/5[x,y,z];", - "F = R^3" - }, - "A list of indices can be used to produce homomorphisms corresponding to the corresponding basis vectors.", - EXAMPLE { - "F_{0,1,2}", - "F_{0,1}", - "F_{1,2}" - }, - "Matrices are viewed as linear transformations.", - EXAMPLE { - "f = matrix{{x,y,z}}" - }, + "There are three common ways to construct maps between modules. For maps + specified by images of generators, use ", TO "module homomorphisms", " and + the command ", TO map, ". For projection and inclusion maps coming from + selected basis elements, see ", TO "maps between modules", ". For natural + maps induced by inclusions, quotients, kernels, images, or cokernels, use + ", TO inducedMap, ".", + PARA{}, + "Matrices are viewed as linear transformations, but the target and source + matter. Use ", TO source, ", ", TO target, ", and ", TO isWellDefined, + " when checking that a matrix really defines the module map you intend.", -- "The standard way to define a map from an R-module M to an -- R-module N is to give a matrix whose columns are the image vectors -- of the generators of M.", @@ -750,12 +758,29 @@ document { "usual information: source, target, ring.", } --- no links to this node --* -- Mike wanted this: document { Key => "kernel, cokernel and image of a map of modules", + "For a map of modules, the most common associated modules are its ", + TO kernel, ", ", TO image, ", and ", TO cokernel, ". These commands + measure, respectively, the relations killed by the map, the submodule + reached by the map, and the quotient of the target by that image.", + PARA{}, + "Use ", TO source, " and ", TO target, " to check the direction of the + map before interpreting these modules. The predicates ", TO isInjective, + " and ", TO isSurjective, " test whether the kernel or cokernel is zero, + and ", TO isWellDefined, " checks that the proposed matrix actually gives + a well-defined map between the requested modules.", + SeeAlso => { + (kernel, Matrix), + (image, Matrix), + (cokernel, Matrix), + source, + target, + isInjective, + isSurjective, + isWellDefined + } } -*- -* -- Mike wanted this: @@ -867,9 +892,11 @@ document { document { Key => "maps between modules", -- map - "Maps between free modules are usually specified as matrices, as - described in the section on ", TO "matrices", ". In this section - we cover a few other techniques.", + "Use this page as a command index for maps between modules. Maps between + free modules are usually specified as matrices, as described in the section + on ", TO "matrices", ". For maps between submodules, quotients, and + subquotients, start with ", TO "module homomorphisms", " or ", TO inducedMap, + ".", PARA{}, "Let's set up a ring, a matrix, and a free module.", EXAMPLE { @@ -897,8 +924,9 @@ document { Key => "computing syzygies", "A syzygy among the columns of a matrix is, by definition, an element of the kernel of the corresponding map between free modules, - and the easiest way to compute the syzygies applying the - function ", TO "kernel", ".", + and the easiest way to compute the syzygies is often to apply the + function ", TO "kernel", ". Use ", TO "syz", " when you want the + syzygy command directly or need its computation options.", EXAMPLE { "R = QQ[x..z];", "f = vars R", diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_ringmaps.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_ringmaps.m2 index e7d5c4d713f..b433f8cc873 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_ringmaps.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_ringmaps.m2 @@ -90,6 +90,18 @@ document { document { Key => "substitution and maps between rings", HEADER2 "An overview", + "Use this page when you need to move objects between rings, substitute + values for variables, construct a ring map, or compute implicit equations + from a parametrization.", + PARA{}, + "Common ring-map tasks are routed as follows.", + UL { + {"To substitute values or move an object to a related ring, start with ", TO substitute, ", ", TO "substituting values for variables", ", and ", TO "working with multiple rings", "."}, + {"To define a map between rings, use ", TO map, " and then inspect it with ", TO source, ", ", TO target, ", and ", TT ".matrix", "."}, + {"To apply or compose maps, see ", TO "evaluation and composition of ring maps", ", ", TO (symbol SPACE, RingMap, RingElement), ", and ", TO (symbol *, RingMap, RingMap), "."}, + {"To find equations, images, or inverse images, use ", TO "kernel and coimage of a ring map", ", ", TO (kernel, RingMap), ", ", TO coimage, ", ", TO (preimage, RingMap, Ideal), ", ", TO graphIdeal, ", and ", TO graphRing, "."} + }, + PARA{}, Subnodes => { TO substitute, TO "substituting values for variables", @@ -278,6 +290,10 @@ document { document { Key => "basic construction, source and target of a ring map", + "Use this page when you know the images of the variables in a source + ring and want to build the corresponding map. In Macaulay2 the target + ring is given first, the source ring second, and the images of the source + variables third.", SUBSECTION "constructing a ring map", "Use the function ", TO "map", " to construct a map @@ -330,6 +346,9 @@ document { document { Key => "evaluation and composition of ring maps", + "After a ring map is constructed, apply it to elements, ideals, matrices, + vectors, and some modules using function notation. Compose two ring maps + with ", TO (symbol*,RingMap,RingMap), ".", SUBSECTION "evaluating ring maps", "Once a ring map ", TT "F", " is defined, the image of an @@ -360,10 +379,14 @@ document { document { Key => "kernel and coimage of a ring map", - "The kernel and coimage of a ring map can be computed - using ", TO "coimage", " and ", TO2(kernel, "ker"), " . The output - of ", TT "ker", " is an ideal and the output of ", TT "coimage", " is a - ring or quotient ring.", + "Use this page when a map is described parametrically and you want the + equations it satisfies. The kernel of a ring map is an ideal in the + source; it is often the implicit ideal of the parametrized image. The + coimage is the quotient of the source by that kernel.", + PARA{}, + "The kernel and coimage of a ring map can be computed using ", TO "coimage", + " and ", TO2(kernel, "ker"), ". The output of ", TT "ker", " is an ideal + and the output of ", TT "coimage", " is a ring or quotient ring.", EXAMPLE { "R = QQ[x,y,w]; U = QQ[s,t]/ideal(s^4+t^4);", "H = map(U,R,matrix{{s^2,s*t,t^2}})", @@ -372,6 +395,15 @@ document { } -- if module and ring map are homogeneous, and Hilbert F is known, -- this is used in computing the kernel (or coimage). + , + SeeAlso => { + (kernel, RingMap), + coimage, + (preimage, RingMap, Ideal), + graphIdeal, + graphRing, + "elimination of variables" + } } undocumented { (symbol SPACE, RingMap, Number) From 928fe76a3c53144cc29807fa58263297865414f5 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 18:33:14 -0400 Subject: [PATCH 30/73] Add Triplet documentation example --- M2/Macaulay2/packages/Triplets.m2 | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/M2/Macaulay2/packages/Triplets.m2 b/M2/Macaulay2/packages/Triplets.m2 index da8b9f27985..523b6dd434d 100644 --- a/M2/Macaulay2/packages/Triplets.m2 +++ b/M2/Macaulay2/packages/Triplets.m2 @@ -719,7 +719,15 @@ document { the compatibility conditions for degree and homology triplets, respectively. The routine ", TO toHomology, " converts from a degree triplet to a homology triplet, and - the routine ", TO toDegree, " converts from a homology triplet to a degree triplet." + the routine ", TO toDegree, " converts from a homology triplet to a degree triplet.", + EXAMPLE lines /// + T = triplet({1,2,3}, {0,2}, {0,2,3}) + instance(T, Triplet) + isDegreeTriplet T + Th = toHomology T + instance(Th, Triplet) + isHomologyTriplet Th + /// } From 8e679755998008ca1f57bf6a5e46cf263526bfe3 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 18:38:33 -0400 Subject: [PATCH 31/73] Add attemptsAtGenericReduction documentation example --- M2/Macaulay2/packages/TorAlgebra.m2 | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/M2/Macaulay2/packages/TorAlgebra.m2 b/M2/Macaulay2/packages/TorAlgebra.m2 index 48bf5fccd30..314c0111957 100644 --- a/M2/Macaulay2/packages/TorAlgebra.m2 +++ b/M2/Macaulay2/packages/TorAlgebra.m2 @@ -1488,11 +1488,25 @@ doc /// Key attemptsAtGenericReduction Headline - see setAttemptsAtGenericReduction + number of attempts to compute Bass numbers via a generic reduction Description Text - See @TO setAttemptsAtGenericReduction@ + The value stored in {\tt R.attemptsAtGenericReduction} controls how many + attempts are made to reduce {\tt R} modulo a generic regular sequence + when Bass numbers are computed by @TO torAlgClass@. Use + @TO setAttemptsAtGenericReduction@ to set this value. + + Example + Q = ZZ/2[u,v,w,x,y,z]; + R = Q/ideal(x*y,y*z,x^3,x^2*z,x*z^2-y^3,z^3); + R.?attemptsAtGenericReduction + setAttemptsAtGenericReduction(R,100) + R.attemptsAtGenericReduction + + SeeAlso + setAttemptsAtGenericReduction + torAlgClass /// From 627c5e6c72eb856a4ac35085567ecd6b0af6ce83 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 18:58:32 -0400 Subject: [PATCH 32/73] Add SymmetricPolynomials package example --- M2/Macaulay2/packages/SymmetricPolynomials.m2 | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/M2/Macaulay2/packages/SymmetricPolynomials.m2 b/M2/Macaulay2/packages/SymmetricPolynomials.m2 index d37f1c47ae6..82897ab5a15 100644 --- a/M2/Macaulay2/packages/SymmetricPolynomials.m2 +++ b/M2/Macaulay2/packages/SymmetricPolynomials.m2 @@ -86,7 +86,16 @@ document { Headline => "the algebra of symmetric polynomials", PARA{"This package uses an explicit description of the Groebner basis of the ideal of obvious relations in this algebra based on:"}, PARA{"Grayson, Stillmann - Computations in the intersection theory of flag varieties, preprint, 2009"}, - PARA{"Sturmfels - Algorithms in Invariant Theory, Springer Verlag, Vienna, 1993"} + PARA{"Sturmfels - Algorithms in Invariant Theory, Springer Verlag, Vienna, 1993"}, + PARA{"Use ", TO elementarySymmetric, " to express a symmetric polynomial in terms of elementary symmetric functions, and use ", TO (elementarySymmetric,PolynomialRing), " to construct the corresponding map."}, + EXAMPLE lines /// + n=5; + R=QQ[x_1..x_n]; + f=(product gens R)*(sum gens R); + elementarySymmetric f + elementarySymmetric R + ///, + SeeAlso => {elementarySymmetric, buildSymmetricGB} } document { From 6b6c8a60e10cd5f6fad62f3c310554b875de822d Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 19:04:39 -0400 Subject: [PATCH 33/73] Update author emails and MatrixSchubert references --- M2/Macaulay2/packages/MatrixSchubert.m2 | 8 ++-- .../MatrixSchubertConstructionsDOC.m2 | 48 +++++++++---------- M2/Macaulay2/packages/VirtualResolutions.m2 | 2 +- 3 files changed, 29 insertions(+), 29 deletions(-) diff --git a/M2/Macaulay2/packages/MatrixSchubert.m2 b/M2/Macaulay2/packages/MatrixSchubert.m2 index 0bc4f0e595e..453629aed7f 100644 --- a/M2/Macaulay2/packages/MatrixSchubert.m2 +++ b/M2/Macaulay2/packages/MatrixSchubert.m2 @@ -6,19 +6,19 @@ newPackage( Keywords => {"Combinatorics", "Commutative Algebra"}, Authors => { {Name => "Ayah Almousa", - Email => "aalmousa@sc.edu", + Email => "aalmousa@uky.edu", HomePage => "http://sites.google.com/view/ayah-almousa"}, {Name=> "Sean Grate", - Email => "sean.grate@auburn.edu", + Email => "sgrate@iastate.edu", HomePage => "https://seangrate.com/"}, {Name => "Daoji Huang", - Email => "dhuang@ias.edu", + Email => "daojihuang@umass.edu", HomePage => "https://daojihuang.me"}, {Name => "Patricia Klein", Email => "pjklein@tamu.edu", HomePage => "https://patriciajklein.github.io/"}, {Name => "Adam LaClair", - Email => "alaclair@purdue.edu", + Email => "alaclair2@unl.edu", HomePage=> "https://sites.google.com/view/adamlaclair/home"}, {Name => "Yuyuan Luo", Email => "yuyuan.luo@princeton.edu", diff --git a/M2/Macaulay2/packages/MatrixSchubert/MatrixSchubertConstructionsDOC.m2 b/M2/Macaulay2/packages/MatrixSchubert/MatrixSchubertConstructionsDOC.m2 index 3a255071cc4..fc1c8e2c1d9 100644 --- a/M2/Macaulay2/packages/MatrixSchubert/MatrixSchubertConstructionsDOC.m2 +++ b/M2/Macaulay2/packages/MatrixSchubert/MatrixSchubertConstructionsDOC.m2 @@ -13,37 +13,37 @@ doc /// Description Text This package provides functions for constructing and investigating matrix Schubert varieties. Many of the functions in this package can take as input either a permutation in 1-line notation, or an alternating sign matrix. - Text - @UL { - {"[CV20] Aldo Conca and Matteo Varbaro, ", - HREF("https://arxiv.org/abs/1805.11923", EM "Square-free Gröbner degenerations"), - ", Inventiones mathematicae, 221(3), pp.713-730."}, - {"[Ful92] William Fulton, ", - HREF("https://sites.math.washington.edu/~billey/classes/schubert.library/fulton.essential.set.pdf", - EM "Flags, Schubert polynomials, degeneracy loci, and determinantal formulas"), - ", Duke Math J. 65 (1992): 381-420."}, - {"[KM05] Allen Knutson and Ezra Miller, ", - HREF("https://arxiv.org/abs/math/0110058", EM "Gröbner geometry of Schubert polynomials"), - ", Annals of Mathematics (2005): 1245-1318."}, - {"[KW21] Patricia Klein and Anna Weigandt, ", - HREF("https://arxiv.org/abs/2108.08370", EM "Bumpless pipe dreams encode Gröbner geometry of Schubert polynomials"), - ", arxiv preprint 2108.08370."}, - {"[PSW24] Oliver Pechenik, David Speyer, and Anna Weigandt, ", - HREF("https://arxiv.org/abs/2111.10681", EM "Castelnuovo-Mumford regularity of matrix Schubert varieties"), - ", Selecta Mathematica New Series 30, 66 (2024)."}, - {"[Wei17] Anna Weigandt, ", - HREF("https://arxiv.org/abs/1708.07236", EM "Prism tableaux for alternating sign matrix varieties"), - ", arXiv preprint 1708.07236."} - }@ Text @SUBSECTION "Contributors"@ Text The following people have generously contributed code, improved existing code, or enhanced the documentation: @HREF("https://sites.google.com/illinois.edu/shiliang-gao", "Shiliang Gao")@, @HREF("https://www.math.tamu.edu/directory/graduate.html", "Pooja Joshi")@, - @HREF("https://www-users.cse.umn.edu/~mahrud/", "Mahrud Sayrafi")@, and + @HREF("https://www-users.cse.umn.edu/~mahrud/", "Mahrud Sayrafi")@, and @HREF("https://www.clemson.edu/science/academics/departments/mathstat/about/profiles/arakoto", "Antsa Tantely Fandresena Rakotondrafara")@. - We also thank the anonymous referees for their helpful suggestions. + We also thank the anonymous referees for their helpful suggestions. + References + @UL { + {"[CV20] Aldo Conca and Matteo Varbaro, ", + HREF("https://arxiv.org/abs/1805.11923", EM "Square-free Gröbner degenerations"), + ", Inventiones mathematicae, 221(3), pp.713-730."}, + {"[Ful92] William Fulton, ", + HREF("https://sites.math.washington.edu/~billey/classes/schubert.library/fulton.essential.set.pdf", + EM "Flags, Schubert polynomials, degeneracy loci, and determinantal formulas"), + ", Duke Math J. 65 (1992): 381-420."}, + {"[KM05] Allen Knutson and Ezra Miller, ", + HREF("https://arxiv.org/abs/math/0110058", EM "Gröbner geometry of Schubert polynomials"), + ", Annals of Mathematics (2005): 1245-1318."}, + {"[KW21] Patricia Klein and Anna Weigandt, ", + HREF("https://arxiv.org/abs/2108.08370", EM "Bumpless pipe dreams encode Gröbner geometry of Schubert polynomials"), + ", arxiv preprint 2108.08370."}, + {"[PSW24] Oliver Pechenik, David Speyer, and Anna Weigandt, ", + HREF("https://arxiv.org/abs/2111.10681", EM "Castelnuovo-Mumford regularity of matrix Schubert varieties"), + ", Selecta Mathematica New Series 30, 66 (2024)."}, + {"[Wei17] Anna Weigandt, ", + HREF("https://arxiv.org/abs/1708.07236", EM "Prism tableaux for alternating sign matrix varieties"), + ", arXiv preprint 1708.07236."} + }@ SeeAlso "Investigating matrix Schubert varieties" "Investigating ASM varieties" diff --git a/M2/Macaulay2/packages/VirtualResolutions.m2 b/M2/Macaulay2/packages/VirtualResolutions.m2 index c92ac992da5..22f6e6eeb45 100644 --- a/M2/Macaulay2/packages/VirtualResolutions.m2 +++ b/M2/Macaulay2/packages/VirtualResolutions.m2 @@ -16,7 +16,7 @@ newPackage ("VirtualResolutions", Date => "May 06, 2021", Headline => "Methods for virtual resolutions on products of projective spaces", Authors =>{ - {Name => "Ayah Almousa", Email => "aka66@cornell.edu", HomePage => "http://pi.math.cornell.edu/~aalmousa "}, + {Name => "Ayah Almousa", Email => "aalmousa@uky.edu", HomePage => "http://pi.math.cornell.edu/~aalmousa "}, {Name => "Christine Berkesch", Email => "cberkesc@umn.edu", HomePage => "http://math.umn.edu/~cberkesc/"}, {Name => "Juliette Bruce", Email => "jebruce2@wisc.edu", HomePage => "https://juliettebruce.github.io"}, {Name => "David Eisenbud", Email => "de@msri.org", HomePage => "http://www.msri.org/~de/"}, From b7e15f83eb9d60301c1882f761f314687d48e5a4 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 19:12:05 -0400 Subject: [PATCH 34/73] Add Tableaux package example --- M2/Macaulay2/packages/Tableaux/documentation.m2 | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/M2/Macaulay2/packages/Tableaux/documentation.m2 b/M2/Macaulay2/packages/Tableaux/documentation.m2 index 323b7cf6ff1..26bb361cc36 100644 --- a/M2/Macaulay2/packages/Tableaux/documentation.m2 +++ b/M2/Macaulay2/packages/Tableaux/documentation.m2 @@ -10,6 +10,17 @@ Node This package provides the classes @TO YoungTableau@, @TO MutableYoungTableau@, and @TO Tabloid@. These classes can be used to construct (skew) tableaux, and entries in the boxes may be any class. See the constructor's page @TO youngTableau@ for some basics of this class. + Example + lam = new Partition from {4,3,2} + mu = new Partition from {3,1} + T = youngTableau(lam, mu, {1,2,3,3,9}) + allStandardTableaux(new Partition from {2,1}) + SeeAlso + youngTableau + mutableYoungTableau + tabloid + allStandardTableaux + allSemistandardTableaux /// doc /// From fb1b2d4c3310fe58f1d4d3d062f4e052bb29dd85 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 19:17:04 -0400 Subject: [PATCH 35/73] Add SimplicialPosets package example --- M2/Macaulay2/packages/SimplicialPosets.m2 | 25 +++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/M2/Macaulay2/packages/SimplicialPosets.m2 b/M2/Macaulay2/packages/SimplicialPosets.m2 index f2e32f6581d..861b22f20d5 100644 --- a/M2/Macaulay2/packages/SimplicialPosets.m2 +++ b/M2/Macaulay2/packages/SimplicialPosets.m2 @@ -240,16 +240,26 @@ doc /// A package for working with simplicial posets. Description Text - - The primary purpose of this package is to implement the simplicial - poset ring as defined by Richard P. Stanley in 1989. + The primary purpose of this package is to implement the simplicial + poset ring as defined by Richard P. Stanley in 1989. - @HREF("https://www.semanticscholar.org/paper/f-vectors-and-h-vectors-of-simplicial-posets-Stanley/2787117152700af2abce3126dd7ba2325685d78b","Stanley's original paper.")@ + @HREF("https://www.semanticscholar.org/paper/f-vectors-and-h-vectors-of-simplicial-posets-Stanley/2787117152700af2abce3126dd7ba2325685d78b","Stanley's original paper.")@ + Example + P = fromFVector({1,6,5,1}); + I = stanleyPosetIdeal(P); + R = ring(I)/I; + getFVector(P) + isSimplicial(P) Acknowledgement - This package uses some code from the @TO "Posets"@ package. - - Thanks to @HREF("http://www-users.math.umn.edu/~reiner/","Victor Reiner")@. This project was his idea. + This package uses some code from the @TO "Posets"@ package. + + Thanks to @HREF("http://www-users.math.umn.edu/~reiner/","Victor Reiner")@. This project was his idea. + SeeAlso + fromFVector + stanleyPosetIdeal + isSimplicial + "Example: Calculating a Stanley simplicial poset ring" /// -- Example @@ -518,4 +528,3 @@ end-- restart installPackage("SimplicialPosets") - From 54349bbce5e6646362f360c985434f5716f88100 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 19:18:33 -0400 Subject: [PATCH 36/73] Add LineageTable documentation example --- M2/Macaulay2/packages/ThreadedGB.m2 | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/M2/Macaulay2/packages/ThreadedGB.m2 b/M2/Macaulay2/packages/ThreadedGB.m2 index 6a98b5709fe..826521126ae 100644 --- a/M2/Macaulay2/packages/ThreadedGB.m2 +++ b/M2/Macaulay2/packages/ThreadedGB.m2 @@ -473,11 +473,21 @@ doc /// A lineage table is a hashtable whose values are a Gröbner basis for the ideal {\tt I} or the ideal generated by {\tt L}, and keys are the lineages of the corresponding elements. - A lineage of a polynomial is a natural number, or an ordered pair of lineages, tracing + A lineage of a polynomial is a natural number, or an ordered pair of lineages, tracing its history in the given Gröbner basis computation. Lineages that are natural numbers are assigned to the original input polynomials. + Example + R = ZZ/101[x,y,z, MonomialOrder=>Lex]; + I = ideal {2*x + 10*y^2*z, 8*x^2*y + 10*x*y*z^3}; + allowableThreads = 2; + H = tgb I + instance(H, LineageTable) + matrix H SeeAlso tgb + (minimize, LineageTable) + (reduce, LineageTable) + (matrix, LineageTable) /// doc /// Key From 9200dc4424ceee98337bec65086065383b397900 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 19:20:27 -0400 Subject: [PATCH 37/73] Add StronglyStableIdeals package example --- M2/Macaulay2/packages/StronglyStableIdeals.m2 | 25 ++++++++++++++----- 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/M2/Macaulay2/packages/StronglyStableIdeals.m2 b/M2/Macaulay2/packages/StronglyStableIdeals.m2 index 488b5de9679..70cb692d642 100644 --- a/M2/Macaulay2/packages/StronglyStableIdeals.m2 +++ b/M2/Macaulay2/packages/StronglyStableIdeals.m2 @@ -677,14 +677,27 @@ doc /// {\it Strongly stable ideals and segment ideals:} @TO lexIdeal@ -- Compute the saturated lexicographic ideal with a given Hilbert polynomial. - + @TO stronglyStableIdeals@ -- Compute the saturated strongly stable ideals with a given Hilbert polynomial. - - @TO isGenSegment@ -- Test whether there exists a term ordering such that each minimal generator of a strongly stable ideal is greater than all monomials of the same degree outside the ideal. - - @TO isRegSegment@ -- Test whether the truncation of a strongly stable ideal in degree equal to its regularity is a segment. - @TO isHilbSegment@ -- Test whether the truncation of a strongly stable ideal in degree equal to the Gotzmann number of its Hilbert polynomial is a segment. + @TO isGenSegment@ -- Test whether there exists a term ordering such that each minimal generator of a strongly stable ideal is greater than all monomials of the same degree outside the ideal. + + @TO isRegSegment@ -- Test whether the truncation of a strongly stable ideal in degree equal to its regularity is a segment. + + @TO isHilbSegment@ -- Test whether the truncation of a strongly stable ideal in degree equal to the Gotzmann number of its Hilbert polynomial is a segment. + Example + QQ[t]; + isHilbertPolynomial(3*t+4) + gotzmannNumber(3*t+4) + ideals = stronglyStableIdeals(3, 3); + #ideals + ideals#0 + SeeAlso + isHilbertPolynomial + gotzmannNumber + gotzmannDecomposition + stronglyStableIdeals + lexIdeal /// doc /// From f506cfca921d8ed98583d3ab58348ca3d3d253fc Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 19:31:49 -0400 Subject: [PATCH 38/73] Add package examples for fitting ideals and Fourier-Motzkin --- M2/Macaulay2/packages/FiniteFittingIdeals.m2 | 5 +++++ M2/Macaulay2/packages/FourierMotzkin.m2 | 8 +++++++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/M2/Macaulay2/packages/FiniteFittingIdeals.m2 b/M2/Macaulay2/packages/FiniteFittingIdeals.m2 index cb0af4e673a..d9ddedbbc18 100644 --- a/M2/Macaulay2/packages/FiniteFittingIdeals.m2 +++ b/M2/Macaulay2/packages/FiniteFittingIdeals.m2 @@ -191,6 +191,11 @@ document { " by Gustav Sædén Ståhl.", PARA{}, "The following is an example illustrating the main functions provided in the package.", + EXAMPLE { + "S = ZZ[x_0,x_1]", + "quotScheme(S^2,1,{0})" + }, + UL { {TO "Fitting ideals of finite modules"}, }, diff --git a/M2/Macaulay2/packages/FourierMotzkin.m2 b/M2/Macaulay2/packages/FourierMotzkin.m2 index 2bc0d1d07f9..e1d389d3dae 100644 --- a/M2/Macaulay2/packages/FourierMotzkin.m2 +++ b/M2/Macaulay2/packages/FourierMotzkin.m2 @@ -264,6 +264,13 @@ document { PARA{}, "Here are some examples illustrating some uses of this package.", + EXAMPLE { + "R = matrix(QQ, {{1,0},{0,1}})", + "H = fourierMotzkin R", + "H#0", + "fourierMotzkin H" + }, + UL { {TO "Finding the facets of the cyclic polytope"}, {TO "Finding the facets of the permutahedron"}, @@ -626,4 +633,3 @@ path = prepend(homeDirectory | "Code/", path); installPackage "FourierMotzkin" check "FourierMotzkin" - From 7eff552d6d011a9ebcd50f0c9a448e4ad151f626 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 23:34:41 -0400 Subject: [PATCH 39/73] Update package documentation examples and TODOs --- M2/Macaulay2/packages/ExampleSystems.m2 | 6 +++- M2/Macaulay2/packages/LocalRings/doc.m2 | 11 ++++--- M2/Macaulay2/packages/Saturation/doc.m2 | 14 +++++---- .../packages/Saturation/quotient-doc.m2 | 31 +++++++------------ .../packages/Saturation/saturate-doc.m2 | 19 ++++++------ .../packages/VirtualResolutions/doc.m2 | 25 +++++++++++++++ 6 files changed, 64 insertions(+), 42 deletions(-) diff --git a/M2/Macaulay2/packages/ExampleSystems.m2 b/M2/Macaulay2/packages/ExampleSystems.m2 index e1e559ce9f6..ad4f7f71d19 100644 --- a/M2/Macaulay2/packages/ExampleSystems.m2 +++ b/M2/Macaulay2/packages/ExampleSystems.m2 @@ -73,6 +73,11 @@ doc /// This package is a database for examples of polynomial systems in Macaulay2, including standard systems of interest in various applications, such as engineering, chemistry, robotics, and economics. + Example + cyclic(5, QQ) + Text + The package exports each named system as a function; the example above + returns the cyclic 5-roots system over the rational numbers. {\bf References:} Code @@ -204,4 +209,3 @@ substitute(ExampleTable, List) := (E, L) -> ( ) substitute(ExampleTable, Option) := (E,subs) -> substitute(E, {subs}) - diff --git a/M2/Macaulay2/packages/LocalRings/doc.m2 b/M2/Macaulay2/packages/LocalRings/doc.m2 index 879049b7359..6dfe9f57ccf 100644 --- a/M2/Macaulay2/packages/LocalRings/doc.m2 +++ b/M2/Macaulay2/packages/LocalRings/doc.m2 @@ -1,5 +1,3 @@ -undocumented { presentationComplex } - doc /// Key LocalRings @@ -181,10 +179,9 @@ Node (symbol_, PolynomialRing, Ideal) (symbol_, PolynomialRing, RingElement) Headline - Constructor for local rings + Constructor for local rings at prime ideals Usage R_P - R_f localRing(R, P) Inputs R:PolynomialRing @@ -192,7 +189,7 @@ Node P:Ideal a prime ideal for the localization f:RingElement - a ring element to localize (not yet implemented) + a ring element; localization by a single element is not implemented Outputs :LocalRing the local ring $R_{\mathfrac p}$ @@ -209,6 +206,10 @@ Node Text Note that the ideal $P$ is assumed to be prime. Use @TO (isWellDefined, LocalRing)@ to confirm that a local ring is well defined. + Text + The syntax @TT "R_f"@ is reserved for localization by inverting a single ring element, + but this operation is not currently implemented in this package. Use @TT "R_P"@ or + @TT "localRing(R,P)"@ for localization at a prime ideal @TT "P"@. Node Key diff --git a/M2/Macaulay2/packages/Saturation/doc.m2 b/M2/Macaulay2/packages/Saturation/doc.m2 index 17de1336f2e..2d35614f0b9 100644 --- a/M2/Macaulay2/packages/Saturation/doc.m2 +++ b/M2/Macaulay2/packages/Saturation/doc.m2 @@ -49,7 +49,6 @@ Node Ih = homogenize(I, d) saturate(Ih, d) --- TODO Node Key "module quotients, saturation, and annihilator" @@ -62,14 +61,17 @@ Node Similar to the case of ideals, the @TO2 {(quotient, Module, Module), "quotient"}@ of two $R$-modules $M, N$ contained in the same @TO ambient@ module is an ideal $M:N$ of elements $f\in R$ such that $f N \subset M$. This is equivalent to the @TO annihilator@ of the quotient module $(M+N)/M$. --- TODO: --- Example + Example + R = QQ[x,y,z]; + M = image matrix{{x^2,x*y,0},{0,0,z}} + N = image matrix{{x,0},{0,z}} + M:N Text --- TODO: what is the ambient module assumed to be? The @TO2 {(quotient, Module, Ideal), "quotient"}@ of an $R$-module $M\subset F$ with respect to an ideal $J\subset R$ is the module $M:_F J$ of elements $f\in F$ such that $J f\subset M$. --- TODO: --- Example + The ambient module $F$ is the ambient module of @TT "M"@. + Example + M : ideal x Text @SUBSECTION "Saturation of Modules"@ diff --git a/M2/Macaulay2/packages/Saturation/quotient-doc.m2 b/M2/Macaulay2/packages/Saturation/quotient-doc.m2 index 4545f4f13fe..c05a39387b7 100644 --- a/M2/Macaulay2/packages/Saturation/quotient-doc.m2 +++ b/M2/Macaulay2/packages/Saturation/quotient-doc.m2 @@ -1,9 +1,3 @@ -undocumented { - (quotient, Ideal, Number), (symbol:, Ideal, Number), - (quotient, Module, Number), (symbol:, Module, Number) - } - --- TODO: why does this node show up as an orphan in the table of contents? doc /// Node Key @@ -12,15 +6,19 @@ Node (symbol:, Module, Module) -- return an ideal (quotient, Ideal, Ideal) + (quotient, Ideal, Number) (quotient, Ideal, RingElement) (quotient, MonomialIdeal, RingElement) (symbol:, Ideal, Ideal) + (symbol:, Ideal, Number) (symbol:, Ideal, RingElement) (symbol:, MonomialIdeal, RingElement) -- return a module (quotient, Module, Ideal) + (quotient, Module, Number) (quotient, Module, RingElement) (symbol:, Module, Ideal) + (symbol:, Module, Number) (symbol:, Module, RingElement) [quotient, MinimalGenerators] [quotient, BasisElementLimit] @@ -33,7 +31,7 @@ Node I:J Inputs I:{Ideal,MonomialIdeal,Module} - J:{Ideal,MonomialIdeal,Module,RingElement} + J:{Ideal,MonomialIdeal,Module,RingElement,Number} Strategy=>Thing specifies the algorithm MinimalGenerators=>Boolean @@ -51,14 +49,13 @@ Node if @TT "J"@ is an ideal or ring element, then the result is a submodule containing @TT "I"@. The arguments should be ideals in the same ring, or submodules of the same module. - If the second input @TT "J"@ is a ring element @TT "f"@, then the principal ideal generated by @TT "f"@ is used. + If the second input @TT "J"@ is a ring element or number @TT "f"@, then the principal ideal generated by @TT "f"@ is used. The infix colon operator @TO symbol:@ may be used as an abbreviation, if no options need to be supplied. - -- TODO: rewrite with math - For ideals, the quotient is the set of ring elements $r$ such that $rJ$ is contained in $I$. - If $I$ is a submodule of a module $M$, and $J$ is an ideal, the quotient is the set of elements $m \in M$ - such that $Jm$ is contained in $I$. Finally, if $I$ and $J$ are submodules of the same module $M$, - then the result is the set of ring elements $r$ such that $rJ$ is contained in $I$. + For ideals, the quotient $I:J$ is the ideal of ring elements $r$ such that $rJ\subset I$. + If $I$ is a submodule of an ambient module $M$ and $J$ is an ideal, then $I:J$ is the submodule + of elements $m\in M$ such that $Jm\subset I$. If $I$ and $J$ are submodules of the same ambient + module $M$, then $I:J$ is the ideal of ring elements $r$ such that $rJ\subset I$. Example R = ZZ/32003[a..d]; J = monomialCurveIdeal(R,{1,4,7}) @@ -95,12 +92,12 @@ Node saturate symbol: --- TODO: change to strategy node only for the relevant quotient method keys Node Key [quotient, Strategy] Description Text + The @TT "Strategy"@ option applies to the explicit @TT "quotient"@ methods listed above. Suppose that @TT "I"@ is the image of a free module @TT "FI"@ in a quotient module @TT "G"@, and @TT "J"@ is the image of the free module @TT "FJ"@ in @TT "G"@. @@ -119,12 +116,6 @@ Node If so, it goes on to the third generator; else it intersects @TT "I1"@ with the quotient of @TT "I"@ by the second generator to produce a new @TT "I1"@. It then iterates this process, working through the generators one at a time. --- TODO: not yet implemented - To use @TT "Strategy=>Linear"@ the argument @TT "J"@ must be a principal ideal, generated by a linear form. - A change of variables is made so that this linear form becomes the last variable. Then a reverse lex Gröbner basis - is used, and the quotient of the initial ideal by the last variable is computed combinatorially. - This set of monomial is then lifted back to a set of generators for the quotient. - The following examples show timings for the different strategies. @TT "Strategy => Iterate"@ is sometimes faster for ideals with a small number of generators: Example diff --git a/M2/Macaulay2/packages/Saturation/saturate-doc.m2 b/M2/Macaulay2/packages/Saturation/saturate-doc.m2 index 8d446239d3f..6e8cea78171 100644 --- a/M2/Macaulay2/packages/Saturation/saturate-doc.m2 +++ b/M2/Macaulay2/packages/Saturation/saturate-doc.m2 @@ -1,26 +1,23 @@ -undocumented { - (saturate, Ideal, Number), - (saturate, Vector, Number), - (saturate, Module, Number), - (saturate, Ideal, List), - (saturate, Module, List), - (saturate, Vector, List) - } - doc /// Node Key saturate (saturate, Ideal) (saturate, Ideal, Ideal) + (saturate, Ideal, Number) (saturate, Ideal, RingElement) + (saturate, Ideal, List) (saturate, MonomialIdeal, RingElement) (saturate, Module) (saturate, Module, Ideal) + (saturate, Module, Number) (saturate, Module, RingElement) + (saturate, Module, List) (saturate, Vector) (saturate, Vector, Ideal) + (saturate, Vector, Number) (saturate, Vector, RingElement) + (saturate, Vector, List) [saturate, MinimalGenerators] [saturate, BasisElementLimit] [saturate, DegreeLimit] @@ -32,7 +29,7 @@ Node saturate I Inputs I:{Ideal,MonomialIdeal,Module} - J:{Ideal,MonomialIdeal,Module,RingElement} + J:{Ideal,MonomialIdeal,Module,RingElement,Number,List} if not present, then the ideal generated by the variables of the ring is used Strategy=>Thing specifies the algorithm @@ -48,6 +45,8 @@ Node Text If $I$ is either an ideal or a submodule of a module $M$, the saturation $I : J^\infty$ is defined to be the set of elements $f$ in the ring or $M$ such that $f J^N$ is contained in $I$, for some $N$ large enough. + If @TT "J"@ is a ring element or number, then the principal ideal generated by @TT "J"@ is used. + If @TT "J"@ is a list, then saturation is applied successively with respect to each element of the list. For example, one way to homogenize an ideal is to homogenize the generators and then saturate with respect to the homogenizing variable. diff --git a/M2/Macaulay2/packages/VirtualResolutions/doc.m2 b/M2/Macaulay2/packages/VirtualResolutions/doc.m2 index de6310c7bf6..6816156d75b 100644 --- a/M2/Macaulay2/packages/VirtualResolutions/doc.m2 +++ b/M2/Macaulay2/packages/VirtualResolutions/doc.m2 @@ -137,6 +137,10 @@ doc /// If Strategy is set to @TT "Determinantal"@, isVirtual will check whether the given chain complex is a virtual resolution by checking the depth of the saturation of the ideals of maximal rank from the boundary maps. See Theorem 1.3 of [Loper, @arXiv "1904.05994"@]. + Example + R = ZZ/101[s,t]; + C = res ideal(t); + isVirtual(ideal(s,t), C, Strategy=>"Determinantal") SeeAlso isVirtual /// @@ -185,6 +189,11 @@ doc /// Text If @TT "GeneralElements"@ is set to true, @TO "idealSheafGens"@ will replace all generators of {\tt I} of the same degree with a new generator of the that degree which is a general linear combination of those generators, then run @TT "idealSheafGens"@ on the new ideal. + Example + R = ZZ/101[x_0,x_1,x_2,x_3,x_4,Degrees=>{2:{1,0},3:{0,1}}]; + B = intersect(ideal(x_0,x_1),ideal(x_2,x_3,x_4)); + I = ideal(x_0^2*x_2^2+x_1^2*x_3^2+x_0*x_1*x_4^2, x_0^3*x_4+x_1^3*(x_2+x_3)); + idealSheafGens(2,I,B,GeneralElements=>true); SeeAlso idealSheafGens /// @@ -318,6 +327,10 @@ doc /// in $\PP^3$ intersects the base locus of the projections maps used in this function. If this option is set to true and the given curve does intersect the base locus, an error is returned. + Example + R = ZZ/101[z_0,z_1,z_2,z_3]; + J = ideal(z_0*z_2-z_1^2, z_1*z_3-z_2^2, z_0*z_3-z_1*z_2); + dim curveFromP3toP1P2(J,PreserveDegree=>true) SeeAlso curveFromP3toP1P2 /// @@ -373,6 +386,8 @@ doc /// curve will intersect the base loci of the projections used to construct the curve in $\PP^1\times\PP^2$. If the curve does intersect the base locusi it will generate a new random curve in $\PP^3$. The option @TT "Attempt"@ limits the number of attempts to find a curve disjoint from the base loci before quitting. By default, Attempt is set to 1000. + Example + dim randomCurveP1P2(3,0,Attempt=>50) SeeAlso randomCurveP1P2 /// @@ -496,6 +511,16 @@ doc /// Text When the optional argument @TT "LengthLimit"@ is specified virtualOfPair will stop computing syzygies after the given length is reached, otherwise computation continues until the resolution terminates. + Example + X = toricProjectiveSpace(1) ** toricProjectiveSpace(1); + S = ring X; B = ideal X; + J = saturate(intersect( + ideal(x_1 - 1*x_0, x_3 - 4*x_2), + ideal(x_1 - 2*x_0, x_3 - 5*x_2), + ideal(x_1 - 3*x_0, x_3 - 6*x_2)), + B); + C = virtualOfPair(J, {{3,1}}, LengthLimit=>2); + isVirtual(B, C) SeeAlso virtualOfPair /// From 4db1bd6570e328b397d2047de63ecfa4f8b8da48 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Tue, 19 May 2026 09:04:57 -0400 Subject: [PATCH 40/73] Add RandomIdeals AlexanderProbability example --- M2/Macaulay2/packages/RandomIdeals.m2 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/M2/Macaulay2/packages/RandomIdeals.m2 b/M2/Macaulay2/packages/RandomIdeals.m2 index d9a802bb921..ecd2c3408ce 100644 --- a/M2/Macaulay2/packages/RandomIdeals.m2 +++ b/M2/Macaulay2/packages/RandomIdeals.m2 @@ -960,6 +960,11 @@ Inputs Description Text Controls how often the Alexander dual is taken + Example + setRandomSeed 1 + S = ZZ/2[vars(0..3)] + J = monomialIdeal"ab,ad,bcd" + first randomSquareFreeStep(J, AlexanderProbability => 1.0) SeeAlso randomSquareFreeStep /// @@ -1498,4 +1503,3 @@ installPackage "RandomIdeals" check "RandomIdeals" viewHelp RandomIdeals - From 3ba8ee5b24d9928ee2f0bb108eca9f91506d8a75 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Tue, 19 May 2026 09:30:22 -0400 Subject: [PATCH 41/73] Add package documentation examples --- M2/Macaulay2/packages/JSON.m2 | 7 ++ M2/Macaulay2/packages/Parsing.m2 | 27 +++++++ .../packages/WittVectors/Documentation.m2 | 75 +++++++++++++++++-- 3 files changed, 103 insertions(+), 6 deletions(-) diff --git a/M2/Macaulay2/packages/JSON.m2 b/M2/Macaulay2/packages/JSON.m2 index ae4cd70354a..a0e8c718e29 100644 --- a/M2/Macaulay2/packages/JSON.m2 +++ b/M2/Macaulay2/packages/JSON.m2 @@ -274,6 +274,7 @@ doc /// [toJSON,NameSeparator] [toJSON,Sort] Indent + IndentLevel ValueSeparator NameSeparator Headline @@ -304,6 +305,12 @@ doc /// number of spaces to indent for each level of indentation. Example toJSON(x, Indent => 2) + Text + The @TT "IndentLevel"@ option is used internally to track the current + indentation depth. It can also be set directly to format output as if + it were already nested inside a larger JSON value. + Example + toJSON(x, Indent => 2, IndentLevel => 1) Text Alternatively, the @TT "Indent"@ option can be a string corresponding to the indentation used for each level. diff --git a/M2/Macaulay2/packages/Parsing.m2 b/M2/Macaulay2/packages/Parsing.m2 index 89737e443ea..be0af0b68a0 100644 --- a/M2/Macaulay2/packages/Parsing.m2 +++ b/M2/Macaulay2/packages/Parsing.m2 @@ -175,6 +175,10 @@ document { Key => Parsing, PARA { "See the package ", TO "Classic::Classic", " for a good example of the use of this framework." }, + EXAMPLE lines /// + (ZZParser : charAnalyzer) "-123" + (constParser "abc" : nonspaceAnalyzer) " a b c " + ///, Subnodes => { TO Analyzer, TO Parser, @@ -194,6 +198,13 @@ document { Key => Parser, "When the input stream is exhausted, we call ", TT "p", " one more time like this: ", TT "p null", ". The return value is ", TO "null", " if the parser is not in a terminal state. Otherwise the return value is the parsed (and possibly evaluated) result." }, + EXAMPLE lines /// + p = constParser "abc"; + instance(p, Parser) + q = p "a"; + instance(q, Parser) + (((q "b") "c") null) + ///, Subnodes => { "simple parsers", TO deadParser, @@ -225,6 +236,13 @@ document { Key => Analyzer, Actually, the analyzer is to return a pair: ", TT "(pos,token)", ", where ", TT "pos", " is a string indicating the position where ", TT "token", " was found in the input. A position will be a sort of thing which can be converted to string with ", TO "toString", " (for printing error messages) and can be sorted." }, + EXAMPLE lines /// + instance(charAnalyzer, Analyzer) + a = charAnalyzer "ab"; + a() + a() + a() === null + ///, Subnodes => { TO charAnalyzer, TO nonspaceAnalyzer @@ -273,6 +291,10 @@ document { Key => nonspaceAnalyzer, document { Key => nil, Headline => "a symbol a parser may return to indicate acceptance of the empty string of tokens", + EXAMPLE lines /// + (optP constParser "abc" : charAnalyzer) "" + (optP constParser "abc" : charAnalyzer) "abc" + ///, SeeAlso => { nullParser } } @@ -301,6 +323,11 @@ document { Key => terminalParser, document { Key => nullParser, Headline => "a terminal parser that returns the value nil", SourceCode => nullParser, + EXAMPLE lines /// + nullParser null + nullParser "x" === null + nullParser null === nil + ///, SeeAlso => { nil } } diff --git a/M2/Macaulay2/packages/WittVectors/Documentation.m2 b/M2/Macaulay2/packages/WittVectors/Documentation.m2 index cbdf0260e04..fc1948ac9ce 100644 --- a/M2/Macaulay2/packages/WittVectors/Documentation.m2 +++ b/M2/Macaulay2/packages/WittVectors/Documentation.m2 @@ -8,6 +8,39 @@ doc /// Description Text This package implements finite-length Witt vectors over rings of positive characteristic. The main method is witt, which can be used to build Witt rings, Witt ring maps, and Witt ring elements; Witt ring elements can be added, multiplied, etc. The Frobenius and Verschiebung maps on Witt rings and Witt ring elements are also implemented. The package also includes methods for working with ideals in Witt rings, as well as a method giving an explicit presentation of a Witt ring as a finitely generated algebra over the integers. Finally, there are methods for finding the equations satisfied by the parameters of a Frobenius lift on a quotient of a polynomial ring, as well as computing quasi-F-splitting heights of complete intersections. + Example + R = ZZ/3[x]; + W = witt(2, R) + u = witt{x, x^2}; + v = witt{1_R, x}; + u + v + u * v + wittFrobenius u +/// + + +undocumented { overringMap, WittRing, wittSub, wittGenerators, truncation, WittOverring, makeCoefficientFieldPrime } + + +doc /// + Key + explicit + Headline + Convert Witt objects to explicit presentations. + Usage + E = explicit x + Inputs + x:Thing + Outputs + E:Thing + Description + Text + In this package, @TO explicit@ converts Witt rings, Witt ideals, and + Witt ring maps to ordinary rings, ideals, and maps used for computation. + Example + R = (ZZ/2)[x]; + W = witt(2, R); + explicit W /// @@ -22,6 +55,7 @@ doc /// doc /// Key + witt (witt, ZZ, RingMap) Headline The map induced on Witt rings by a RingMap. @@ -115,6 +149,7 @@ doc /// doc /// Key + baseMap (baseMap, WittRingMap) Headline Returns the underlying RingMap of a WittRingMap @@ -219,6 +254,31 @@ doc /// ------------------------- +doc /// + Key + overring + Headline + The cached overring of a Witt ring. + Usage + WR.overring + Inputs + WR:{WittPolynomialRing, WittQuotientRing} + Outputs + :Ring + Description + Text + The overring of a Witt ring is the ambient ring used for explicit + computations with Witt vectors. This value is also returned by + @TO wittOverring@. + Example + R = (ZZ/2)[x,y]; + WR = witt(3, R); + WR.overring === wittOverring WR + SeeAlso + wittOverring +/// + + doc /// Key wittOverring @@ -356,6 +416,7 @@ doc /// Key fSplittingHeight [fSplittingHeight, MaxHeight] + MaxHeight Headline Finds the quasi-F-split height ht(S/I) of the quotient of the polynomial ring S=(ZZ/p)[x1,...,xn] by an ideal I generated by a regular sequence (f1,...,fm). Usage @@ -442,8 +503,9 @@ doc/// doc /// Key - (wittFrobenius, WittPolynomialRing) - (wittFrobenius, WittQuotientRing) + wittFrobenius + (wittFrobenius, WittPolynomialRing) + (wittFrobenius, WittQuotientRing) Headline The (Witt) Frobenius map of a Witt ring Usage @@ -510,7 +572,8 @@ doc /// doc /// Key - (verschiebung, WittRingElement) + verschiebung + (verschiebung, WittRingElement) Headline The Verschiebung map on an element Usage @@ -927,9 +990,7 @@ doc /// w2 = witt{x^2, y^2}; w3 = witt{x^3, y^3}; WI = wittIdeal(w1, w2, w3) - SeeAlso - wittIdeal - + /// doc /// @@ -1035,6 +1096,7 @@ doc /// findFrobeniusLiftConstraints [findFrobeniusLiftConstraints, PerturbationTerm] [findFrobeniusLiftConstraints, Homogeneous] + PerturbationTerm Headline Finds the equations satisfied by a delta structure on a ring R Usage @@ -1108,6 +1170,7 @@ doc /// [findFrobeniusLift, PerturbationTerm] [findFrobeniusLift, Nontrivial] [findFrobeniusLift, Verbose] + Nontrivial Headline Finds a random lift of the Frobenius Usage From d1b0153b4b05147e2ad5d844177c650094bb2f60 Mon Sep 17 00:00:00 2001 From: klee669 Date: Tue, 19 May 2026 13:17:43 -0400 Subject: [PATCH 42/73] Update numerical packages documentation Various documentation improvements and minor metadata fixes across packages. - Macaulay2Doc/tu_NAG.m2: add inline comment clarifying parameter point and expected solution count. - MonodromySolver.m2: update contact emails for Timothy Duff and Kisun Lee. - MonodromySolver/Documentation.m2: expand and reorganize docs (specializeSystem, createSeedPair example, timing/getTrackTime notes), consolidate and enrich PointArray documentation, remove several small obsolete doc stubs. - NumericalAlgebraicGeometry/doc.m2: add comprehensive docs for evaluateH/evaluateHx/evaluateHt with usage and examples; add and extend specialize/specialize(PH,...) docs and SpecializedParameterHomotopy descriptions and examples; clean up redundant fragments. - SLPexpressions: remove functions from undocumented list and add full documentation for support, printAsSLP, and cCode in SLPexpressions/doc.m2 (headlines, usage, examples). These changes primarily improve user-facing documentation and examples to make homotopy/parameter handling and SLP utilities clearer. --- M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 | 4 +- M2/Macaulay2/packages/MonodromySolver.m2 | 4 +- .../packages/MonodromySolver/Documentation.m2 | 154 +++++-------- .../NumericalAlgebraicGeometry/doc.m2 | 214 ++++++++++++++---- M2/Macaulay2/packages/SLPexpressions.m2 | 12 - M2/Macaulay2/packages/SLPexpressions/doc.m2 | 114 +++++++++- 6 files changed, 332 insertions(+), 170 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 b/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 index 1334f8dd65a..8d41ac153c1 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 @@ -124,8 +124,8 @@ Node matrix{{X,Y}}, matrix{{A*(X-1)^2-B}, {C*(Y+2)^2+D}} ); -- Define a parameter system with parameters A,B,C,D in variables X,Y - p0 = point{{1,1,1,1}}; - sols = solveFamily(p0, F, NumberOfNodes=>3) + p0 = point{{1,1,1,1}}; -- a parameter point + sols = solveFamily(p0, F, NumberOfNodes=>3) -- 4 solutions for a fixed parameter p0 Text One can also compute the permutations induced by the monodromy action. diff --git a/M2/Macaulay2/packages/MonodromySolver.m2 b/M2/Macaulay2/packages/MonodromySolver.m2 index 3e36f73e040..7f890c0de18 100644 --- a/M2/Macaulay2/packages/MonodromySolver.m2 +++ b/M2/Macaulay2/packages/MonodromySolver.m2 @@ -4,10 +4,10 @@ newPackage( Version => "1.16", Date => "May 2023", Authors => { - {Name => "Timothy Duff", Email => "timduff@uw.edu"}, + {Name => "Timothy Duff", Email => "tduff@missouri.edu"}, {Name => "Cvetelina Hill", Email => "cvetelina.hill@math.gatech.edu"}, {Name => "Anders Nedergaard Jensen", Email => "jensen@math.au.dk"}, - {Name => "Kisun Lee", Email => "klee669@math.gatech.edu"}, + {Name => "Kisun Lee", Email => "kisunl@clemson.edu"}, {Name => "Anton Leykin", Email => "leykin@math.gatech.edu"}, {Name => "Jeff Sommars", Email => "sommars1@uic.edu"} }, diff --git a/M2/Macaulay2/packages/MonodromySolver/Documentation.m2 b/M2/Macaulay2/packages/MonodromySolver/Documentation.m2 index 5f8dd5ba05f..683a4be33e5 100644 --- a/M2/Macaulay2/packages/MonodromySolver/Documentation.m2 +++ b/M2/Macaulay2/packages/MonodromySolver/Documentation.m2 @@ -27,7 +27,7 @@ doc /// TO monodromySolve } Text - @TO monodromySolve@ is the core function, whose input may be @ofClass PolySystem@ or $ofClass GateSystem$. + @TO monodromySolve@ is the core function, whose input may be @ofClass PolySystem@ or @ofClass GateSystem@. As an additional input, a seed pair consisting of initial parameter and solution values may be provided. @TO solveFamily@ is a wrapper function that returns specific solutions and parameter values. @TO sparseMonodromySolve@ is a blackbox solver for systems without parameters, that calls the core function. @@ -195,12 +195,26 @@ doc /// in parameter space PS:System with parameters as coefficients + GS:GateSystem + a gate system with parameters Outputs equations:List containing equations of system with parameters specialized at p0 + G0:GateSystem + the gate system obtained by specializing the parameters of GS Headline - specialize parametric system at a point in the parameter space./// - + specialize parametric system at a point in the parameter space. + Description + Text + Specializes the parameters of a parametric system at the point + @TT "p0"@. + Example + R = CC[a,b][x,y]; + F = polySystem {a*x+b*y, x^2-y}; + p0 = point {{2,3}}; + specializeSystem(p0,F) + /// + doc /// Key createSeedPair @@ -569,8 +583,20 @@ doc /// Description Text This only works on graphs which have been modified by a solver. + Example + setRandomSeed 0; + declareVariable \ {A,B,C,D,X,Y}; + F = gateSystem(matrix{{A,B,C,D}},matrix{{X,Y}},matrix{{A*(X-1)^2-B}, {C*(Y+2)^2+D}}); + (p0,x0) = createSeedPair F; + time (V,npaths) = monodromySolve(F,p0,{x0},NumberOfEdges=>3,NumberOfNodes=>5,TargetSolutionCount=>4,Verbose=>false); + getTrackTime V.Graph + Text + time measures the elapsed time for the whole call, including graph construction, and other overhead. + {\tt getTrackTime} reports only the cumulative time spent tracking paths along edges of the homotopy graph. SeeAlso "elapsedTime" + "monodromySolve" + "HomotopyGraph" /// doc /// @@ -601,32 +627,6 @@ doc /// (L, npaths) = dynamicFlowerSolve(polys.PolyMap,p0,{x0}) /// -doc /// - Key - appendPoint - (appendPoint, PointArray, AbstractPoint) - Headline - append a point at the end of a PointArray - Usage - appendPoint(A,p) - Inputs - A:PointArray - p:AbstractPoint - /// - -doc /// - Key - appendPoints - (appendPoints, PointArray, List) - Headline - append a list of points at the end of a PointArray - Usage - appendPoints(A,L) - Inputs - A:PointArray - L:List - /// - doc /// Key completeGraphInit @@ -675,87 +675,39 @@ doc /// "Potential" /// -doc /// - Key - pointArray - Headline - constructor for PointArray - Usage - A = pointArray L - Inputs - L:List - containing objects of type @TO AbstractPoint@ - Outputs - A:PointArray - /// - doc /// Key PointArray - Headline - a container for solutions - Description - Text - PointArray is a data structure that organizes the solutions found - by a solver. Each @TO HomotopyNode @ object V has an associated - PointArray accessed via V.PartialSols. A "fingerprinting" - scheme allows for equality of points to be checked quickly. - /// - -doc /// - Key + pointArray + appendPoint + (appendPoint, PointArray, AbstractPoint) + appendPoints + (appendPoints, PointArray, List) (indices,PointArray) - Headline - returns indices of a PointArray - Usage - indices A - Inputs - A:PointArray - SeeAlso - "indices" - /// - - -doc /// - Key (length, PointArray) - Headline - number of items stored in a PointArray - Usage - length A - Inputs - A:PointArray - SeeAlso - "length" - /// - -doc /// - Key (net, PointArray) - Headline - pretty printing - Usage - net A - Inputs - A:PointArray - SeeAlso - "Net" - /// - -doc /// - Key (member, AbstractPoint, PointArray) Headline - test point membership in a PointArray - Usage - member(p,A) - Inputs - p:AbstractPoint - A:PointArray - SeeAlso - "member" - /// + a container for numerical points + Description + Text + PointArray is a data structure that organizes the solutions found by a solver. + Each @TO "HomotopyNode"@ object V has an associated PointArray accessed via V.PartialSols. + A "fingerprinting" scheme allows for equality of points to be checked quickly. + Example + A = pointArray {} + p = point {{0,0}} + q = point {{1,0}} + r = point {{0,1}} + appendPoint(A,p) + length A + appendPoints(A,{q,r}) + net A + length A + indices A + member(q,A) + /// doc /// Key diff --git a/M2/Macaulay2/packages/NumericalAlgebraicGeometry/doc.m2 b/M2/Macaulay2/packages/NumericalAlgebraicGeometry/doc.m2 index d27834ec804..1729751184f 100644 --- a/M2/Macaulay2/packages/NumericalAlgebraicGeometry/doc.m2 +++ b/M2/Macaulay2/packages/NumericalAlgebraicGeometry/doc.m2 @@ -931,35 +931,98 @@ document { doc /// Key + evaluateH + evaluateHx evaluateHt - (evaluateHt,Homotopy,Matrix,Number) - (evaluateHt,ParameterHomotopy,Matrix,Matrix,Number) - (evaluateHt,SpecializedParameterHomotopy,Matrix,Number) - (evaluateHt,GateHomotopy,Matrix,Number) - Headline - evaluates the derivative of the homotopy with respect to the continuation parameter -/// -doc /// - Key - evaluateHx + (evaluateH,Homotopy,Matrix,Number) (evaluateHx,Homotopy,Matrix,Number) - (evaluateHx,ParameterHomotopy,Matrix,Matrix,Number) - (evaluateHx,SpecializedParameterHomotopy,Matrix,Number) - (evaluateHx,GateHomotopy,Matrix,Number) - Headline - evaluates the jacobian of the homotopy -/// + (evaluateHt,Homotopy,Matrix,Number) -doc /// - Key - evaluateH - (evaluateH,Homotopy,Matrix,Number) (evaluateH,ParameterHomotopy,Matrix,Matrix,Number) + (evaluateHx,ParameterHomotopy,Matrix,Matrix,Number) + (evaluateHt,ParameterHomotopy,Matrix,Matrix,Number) + (evaluateH,SpecializedParameterHomotopy,Matrix,Number) + (evaluateHx,SpecializedParameterHomotopy,Matrix,Number) + (evaluateHt,SpecializedParameterHomotopy,Matrix,Number) + (evaluateH,GateHomotopy,Matrix,Number) + (evaluateHx,GateHomotopy,Matrix,Number) + (evaluateHt,GateHomotopy,Matrix,Number) + Headline - evaluates the homotopy + evaluate a homotopy and its derivatives + + Usage + evaluateH(H,x,t) + evaluateHx(H,x,t) + evaluateHt(H,x,t) + + evaluateH(H,p,x,t) + evaluateHx(H,p,x,t) + evaluateHt(H,p,x,t) + + Description + Text + These methods evaluate a homotopy and its derivatives at a given point. + + @TO evaluateH@ evaluates the homotopy itself, + @TO evaluateHx@ evaluates its Jacobian with respect to the variables, + and @TO evaluateHt@ evaluates the derivative with respect to the + continuation parameter. + + For a @TO ParameterHomotopy@, parameter values must also be supplied. + + Example + variables = declareVariable \ {x,y} + T = inputGate symbol T + + F = matrix{{x^2+y^2-1},{x*y}} + G = matrix{{x^2-y-1},{x+y-1}} + + H = gateHomotopy((1-T)*F + T*G, matrix{{x,y}}, T) + + X0 = matrix{{.2},{0}} + + evaluateH(H,X0,0.5) + evaluateHx(H,X0,0.5) + evaluateHt(H,X0,0.5) + Text + For a @TO ParameterHomotopy@, parameter values must also be supplied. + + Example + variables = declareVariable \ {x,y} + params = declareVariable \ {a,b} + + F = gateSystem( + matrix{params}, + matrix{variables}, + matrix{{a*x*y-1},{x^3+y^2-b}} + ) + + PH = parametricSegmentHomotopy F + + pStart = matrix{{1,2}} + pTarget = matrix{{2,1}} + + pars = transpose(pStart | pTarget) + + X0 = matrix{{.5},{1}} + + evaluateH(PH,pars,X0,0.5) + evaluateHx(PH,pars,X0,0.5) + evaluateHt(PH,pars,X0,0.5) + Text + After the parameter homotopy is specialized using @TO specialize@, + For a @TO ParameterHomotopy@, parameter values must also be supplied. + + Example + H01 = specialize(PH, pars) + + evaluateH(H01,X0,0.5) + evaluateHx(H01,X0,0.5) + evaluateHt(H01,X0,0.5) /// document { @@ -1065,23 +1128,62 @@ doc /// doc /// Key + specialize (specialize, GateSystem, AbstractPoint) + (specialize, ParameterHomotopy, Matrix) Headline - specialize parameters in a gate system + specialize parameters Usage - specialize(G,p) + F = specialize(G,p) + Hp = specialize(H,p) + Inputs + G: + a gate system with parameters + H: + a parameter homotopy + p: + values of the parameters + Outputs + F: + a gate system with parameters specialized + Hp: + a specialized homotopy Description Text - Returns a @TO GateSystem@ with parameters specialized to the given values. + This method specializes parameters by assigning them the values in {\tt p}. + + If {\tt G} is a @TO GateSystem@ that is defined with parameters, + then the output is a @TO GateSystem@ + in which the parameters of {\tt G} have been replaced by the values in + {\tt p}. + Example variables = declareVariable \ {x,y} - params = declareVariable \ {a,b} - Fab = gateSystem(matrix{params}, matrix{variables}, matrix{{a*x*y-1},{x^3+y^2-b}}) - F = specialize(Fab, point{{1,2}}) - p0 = point{{0.1,0.2+ii}} + params = declareVariable \ {a,b} + Fab = gateSystem(matrix{params}, matrix{variables}, matrix{{a*x*y-1},{x^3+y^2-b}}) + F = specialize(Fab, point{{1,2}}) + p0 = point{{0.1,0.2+ii}} evaluate(F,p0) - evaluateJacobian(F,p0) - /// + evaluateJacobian(F,p0) + + Text + If {\tt H} is a @TO ParameterHomotopy@, then the output is a + @TO SpecializedParameterHomotopy@, which can be passed to + @TO trackHomotopy@. + + + Example + variables = declareVariable \ {x,y} + params = declareVariable \ {a,b} + F = gateSystem(matrix{params}, matrix{variables}, matrix{{a*x*y-1},{x^3+y^2-b}}) + PH = parametricSegmentHomotopy F; + parameters PH + (a0,b0) = (1,2); startSolution = point{{1,1}}; + (a1,b1) = (2,1); + H01 = specialize(PH, matrix{{a0,b0,a1,b1}}); + targetSolution = first trackHomotopy(H01,{startSolution}) + assert(norm evaluate(F,matrix{{a1,b1}},matrix targetSolution) < 0.0001) +/// doc /// Key @@ -1312,6 +1414,21 @@ doc /// SpecializedParameterHomotopy Headline a homotopy obtained from a parameter homotopy by specializing parameters + Description + Text + An object @TO GateParameterHomotopy@ with parameters can be specified to this type + by @TO specialize@ + with given parameter values. This type can be passed to @TO trackHomotopy@. + Example + variables = declareVariable \ {x,y} + params = declareVariable \ {a,b} + F = gateSystem(matrix{params}, matrix{variables}, matrix{{a*x*y-1},{x^3+y^2-b}}) + PH = parametricSegmentHomotopy F + (a0,b0) = (1,2); startSolution = point{{1,1}}; + (a1,b1) = (2,1); + H01 = specialize(PH, matrix{{a0,b0,a1,b1}}); + targetSolution = first trackHomotopy(H01,{startSolution}) + assert(norm evaluate(F,matrix{{a1,b1}},matrix targetSolution) < 0.0001) /// doc /// @@ -1329,7 +1446,23 @@ doc /// Description Text An object of this type specializes to a @TO Homotopy@ given values of the parameters. - It is related to @TO GateHomotopy@. + It is related to @TO GateHomotopy@. + Example + variables = declareVariable \ {x,y} + params = declareVariable \ {a,b} + F = gateSystem(matrix{params}, matrix{variables}, matrix{{a*x*y-1},{x^3+y^2-b}}) + PH = parametricSegmentHomotopy F + Text + From a specific parameter values, it can be specialized by @TO specialize@ to output a type + @TO SpecializedParameterHomotopy@, which can be passed to + @TO trackHomotopy@. + Example + (a0,b0) = (1,2); startSolution = point{{1,1}}; + (a1,b1) = (2,1); + H01 = specialize(PH, matrix{{a0,b0,a1,b1}}); + targetSolution = first trackHomotopy(H01,{startSolution}) + assert(norm evaluate(F,matrix{{a1,b1}},matrix targetSolution) < 0.0001) + /// doc /// @@ -1364,24 +1497,7 @@ doc /// Headline the number of variables in the parameter homotopy /// - -doc /// - Key - (specialize, ParameterHomotopy, Matrix) - specialize - Headline - specialize a parameter homotopy - Usage - Hp = specialize(H,p) - Inputs - H: - homotopy - p: - values of parameters - Outputs - Hp:SpecializedParameterHomotopy - specialized homotopy -/// + doc /// Key diff --git a/M2/Macaulay2/packages/SLPexpressions.m2 b/M2/Macaulay2/packages/SLPexpressions.m2 index c7ef17c7d4e..8b63f41d28f 100644 --- a/M2/Macaulay2/packages/SLPexpressions.m2 +++ b/M2/Macaulay2/packages/SLPexpressions.m2 @@ -986,12 +986,6 @@ document { load "./SLPexpressions/doc.m2" undocumented { -printAsSLP, -(printAsSLP,GateMatrix,GateMatrix), -(printAsSLP,List,List), -cCode, -(cCode,GateMatrix,GateMatrix), -(cCode,List,List), constants, (constants,DetGate), (constants,DivideGate), @@ -1006,12 +1000,6 @@ constants, (net,InputGate), (net,ProductGate), (net,SumGate), -(support,DetGate), -(support,DivideGate), -(support,GateMatrix), -(support,InputGate), -(support,ProductGate), -(support,SumGate) } end diff --git a/M2/Macaulay2/packages/SLPexpressions/doc.m2 b/M2/Macaulay2/packages/SLPexpressions/doc.m2 index 0a25b310331..448c3f8ef15 100644 --- a/M2/Macaulay2/packages/SLPexpressions/doc.m2 +++ b/M2/Macaulay2/packages/SLPexpressions/doc.m2 @@ -36,13 +36,119 @@ doc /// DivideGate DetGate Headline - the class of all gates + node types for straight-line programs Description Text - A gate is a building block of an evaluation circuit. For instance, an @TO InputGate@ represents an abstract unit of input, and a @TO SumGate@ takes a list of inputs, and has an output which represents the sum of the inputs. For more information on the types of gates available in this package, as well as how to construct gates, see @TO2{inputGate, "creating input gates"}@. - -/// + Expressions in an SLP are represented by directed acyclic graphs + whose nodes are instances of subclasses of @TO Gate@. + + Code + UL { + "SumGate -- a sum of gates", + "ProductGate -- a product of gates", + "DivideGate -- a quotient of gates", + "DetGate -- a determinant gate" + } + Text + These gates are assembled into @TO GateMatrix@ objects and + eventually compiled into straight-line programs. + + Example + declareVariable \ {x,y} + f = (x+2*y)^2/(3*x-y) + class f + support f + constants f -- shows all constants used in the expression. + /// + + +doc /// + Key + support + (support,InputGate) + (support,SumGate) + (support,ProductGate) + (support,DivideGate) + (support,DetGate) + (support,GateMatrix) + Headline + input gates appearing in an SLP expression + Usage + support f + Inputs + f:Gate + a gate expression + Outputs + L:List + the list of non-constant input gates appearing in f + Description + Text + Returns the input gates that occur in a gate expression, excluding + constant input gates. This is useful for determining which variables + an expression depends on. + Example + declareVariable \ {x,y,z} + f = (x-y)^2 + 3*z + support f + /// + +doc /// + Key + printAsSLP + (printAsSLP,List,List) + (printAsSLP,GateMatrix,GateMatrix) + Headline + print a straight-line program + Usage + printAsSLP(X,F) + Inputs + X:List + input variables + F:List + output expressions + Description + Text + Prints a straight-line program evaluating the given output expressions + in terms of the specified input variables. + Example + declareVariable \ {x,y} + f = (x+y)^2 - x*y + printAsSLP({x,y},{f}) + SeeAlso + cCode + makeSLProgram + /// + + +doc /// + Key + cCode + (cCode,List,List) + (cCode,GateMatrix,GateMatrix) + Headline + generate C code for evaluating a straight-line program + Usage + cCode(X,F) + Inputs + X:List + input variables + F:List + output expressions + Description + Text + Generates C code for evaluating the straight-line program + determined by the output expressions in terms of the specified + input variables. + Example + declareVariable \ {x,y} + f = (x+y)^2 - x*y + cCode({x,y},{f}) + SeeAlso + printAsSLP + makeSLProgram + /// + doc /// Key "creating gates" From 36746f785cf0b37bed0e1b8da54b427063d6cbc0 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 10:17:12 -0400 Subject: [PATCH 43/73] Refresh Macaulay2Doc landing page and computation guides --- .../Macaulay2Doc/ov_analytic_functions.m2 | 26 ++ .../packages/Macaulay2Doc/ov_examples.m2 | 278 ++++++++++++++++++ .../Macaulay2Doc/ov_groebner_bases.m2 | 3 + M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 | 112 +++---- M2/Macaulay2/packages/Macaulay2Doc/shared.m2 | 12 +- 5 files changed, 359 insertions(+), 72 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_analytic_functions.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_analytic_functions.m2 index 3fb8fe12fbb..71ba5976647 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_analytic_functions.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_analytic_functions.m2 @@ -17,6 +17,31 @@ doc /// Node Key "analytic functions" + Description + Text + Analytic functions in Macaulay2 include symbolic constants, special + functions, trigonometric functions, and numerical evaluations over the + standard inexact number types. + Tree + :Selected Packages + > @TOH "EllipticIntegrals :: EllipticIntegrals"@ + > @TOH "FormalGroupLaws :: FormalGroupLaws"@ + > @TOH "EllipticCurves :: EllipticCurves"@ + > @TOH "NumericalAlgebraicGeometry :: NumericalAlgebraicGeometry"@ + > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ + :Core topics + > "Constant" + > "Gamma" + > "zeta" + > "sin" + > "cos" + > "atan2" + SeeAlso + "packages provided with Macaulay2" + "EllipticIntegrals :: EllipticIntegrals" + "FormalGroupLaws :: FormalGroupLaws" + "EllipticCurves :: EllipticCurves" + "NumericalAlgebraicGeometry :: NumericalAlgebraicGeometry" Subnodes Constant -- the class of constants :Special functions @@ -77,6 +102,7 @@ Node document { Key => Constant, + Headline => "the class of constants", PARA { "A constant is a symbolic entity that can be approximated by a real or complex number to any desired accuracy. It is converted to a numeric value of the diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 index b92cbef9104..2d57ce22eb4 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 @@ -2,6 +2,31 @@ doc /// Node Key "elementary arithmetic" + Description + Text + Elementary arithmetic in Macaulay2 includes integer and modular arithmetic, + factorization, gcd/lcm computations, and finite-field calculations. + Tree + :Selected Packages + > @TOH "ConwayPolynomials :: ConwayPolynomials"@ + > @TOH "Cyclotomic :: Cyclotomic"@ + > @TOH "LLLBases :: LLLBases"@ + > @TOH "EllipticCurves :: EllipticCurves"@ + > @TOH "Units :: Units"@ + > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ + :Core topics + > "gcd" + > "lcm" + > "factor" + > "powermod" + > "mod" + SeeAlso + "packages provided with Macaulay2" + "ConwayPolynomials :: ConwayPolynomials" + "Cyclotomic :: Cyclotomic" + "LLLBases :: LLLBases" + "EllipticCurves :: EllipticCurves" + "Units :: Units" Subnodes mod plus @@ -16,9 +41,101 @@ Node gcdCoefficients factor +Node + Key + "linear algebra" + Description + Text + Linear algebra in Macaulay2 includes matrix construction, determinants and + minors, row reduction, matrix decompositions, kernels and inverses, and + related multilinear constructions. + Tree + :Selected Packages + > @TOH "LLLBases :: LLLBases"@ + > @TOH "TensorComplexes :: TensorComplexes"@ + > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ + :Core topics + > "matrix" + > "determinants and minors" + > "rank" + > @TOH "kernel(Matrix)"@ + > @TOH "inverse(Matrix)"@ + > "transpose" + > "reducedRowEchelonForm" + > "LUdecomposition" + > "QRDecomposition" + > "SVD" + > "smithNormalForm" + SeeAlso + "packages provided with Macaulay2" + "LLLBases :: LLLBases" + "TensorComplexes :: TensorComplexes" + Subnodes + @TO "LLLBases :: LLLBases"@ + @TO "TensorComplexes :: TensorComplexes"@ + matrix + "determinants and minors" + rank + "kernel(Matrix)" + "inverse(Matrix)" + transpose + reducedRowEchelonForm + LUdecomposition + QRDecomposition + SVD + smithNormalForm + Node Key "commutative algebra" + Description + Text + Commutative algebra in Macaulay2 centers on ideals, modules, Groebner bases, + syzygies, Hilbert invariants, elimination, and resolution techniques. + Tree + :Tutorials + > "Tutorial: Modules in Macaulay2" + > "Tutorial: Elementary uses of Gröbner bases" + > @TO2("A first course in commutative algebra", "teaching materials")@ + :Selected Packages + > @TOH "IntegralClosure :: IntegralClosure"@ + > @TOH "PrimaryDecomposition :: PrimaryDecomposition"@ + > @TOH "ReesAlgebra :: ReesAlgebra"@ + > @TOH "MinimalPrimes :: MinimalPrimes"@ + > @TOH "Depth :: Depth"@ + > @TOH "Elimination :: Elimination"@ + > @TOH "Saturation :: Saturation"@ + > @TOH "Regularity :: Regularity"@ + > @TOH "LocalRings :: LocalRings"@ + > @TOH "MonomialAlgebras :: MonomialAlgebras"@ + > @TOH "NoetherNormalization :: NoetherNormalization"@ + > @TOH "TangentCone :: TangentCone"@ + > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ + :Core topics + > "Gröbner bases" + > "normal forms" + > "elimination of variables" + > "hilbertFunction" + > "hilbertSeries" + > "hilbertPolynomial" + > @TOH "Complexes :: freeResolution"@ + > @TOH "MinimalPrimes :: radical"@ + > @TOH "MinimalPrimes :: minimalPrimes"@ + > @TOH "PrimaryDecomposition :: primaryDecomposition"@ + > "regularity" + Text + The reference links below are retained for direct access to lower-level commands. + SeeAlso + "packages provided with Macaulay2" + "IntegralClosure :: IntegralClosure" + "PrimaryDecomposition :: PrimaryDecomposition" + "ReesAlgebra :: ReesAlgebra" + "MinimalPrimes :: MinimalPrimes" + "Depth :: Depth" + "Elimination :: Elimination" + "Saturation :: Saturation" + "Regularity :: Regularity" + "LocalRings :: LocalRings" Subnodes "Gröbner bases" "normal forms" @@ -73,6 +190,43 @@ Node Node Key "homological algebra" + Description + Text + Homological algebra in Macaulay2 covers complexes, maps of complexes, + homology and cohomology functors, and derived constructions such as Tor and + Ext. + Tree + :Tutorials + > "Tutorial: Modules in Macaulay2" + :Selected Packages + > @TOH "Complexes :: Complexes"@ + > @TOH "OldChainComplexes :: OldChainComplexes"@ + > @TOH "ChainComplexExtras :: ChainComplexExtras"@ + > @TOH "DGAlgebras :: DGAlgebras"@ + > @TOH "TorAlgebra :: TorAlgebra"@ + > @TOH "SchurFunctors :: SchurFunctors"@ + > @TOH "TensorComplexes :: TensorComplexes"@ + > @TOH "MCMApproximations :: MCMApproximations"@ + > @TOH "KustinMiller :: KustinMiller"@ + > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ + :Core topics + > "Tor" + > "Ext" + > "HH" + > "isExact" + > "kernel" + > "cokernel" + > "image" + SeeAlso + "packages provided with Macaulay2" + "Complexes :: Complexes" + "OldChainComplexes :: OldChainComplexes" + "ChainComplexExtras :: ChainComplexExtras" + "DGAlgebras :: DGAlgebras" + "TorAlgebra :: TorAlgebra" + "SchurFunctors :: SchurFunctors" + "TensorComplexes :: TensorComplexes" + "MCMApproximations :: MCMApproximations" Subnodes kernel cokernel @@ -97,6 +251,46 @@ Node Node Key "algebraic geometry" + Description + Text + Algebraic geometry in Macaulay2 includes computations with affine and + projective varieties, toric and Schubert geometry, singularities, + characteristic classes, and rational points. + Tree + :Tutorials + > "Tutorial: Divisors" + > "Tutorial: Canonical Embeddings of Plane Curves and Gonality" + > "Tutorial: Fano varieties" + :Selected Packages + > @TOH "Varieties :: Varieties"@ + > @TOH "Schubert2 :: Schubert2"@ + > @TOH "NormalToricVarieties :: NormalToricVarieties"@ + > @TOH "CharacteristicClasses :: CharacteristicClasses"@ + > @TOH "HyperplaneArrangements :: HyperplaneArrangements"@ + > @TOH "Points :: Points"@ + > @TOH "RationalPoints :: RationalPoints"@ + > @TOH "PushForward :: PushForward"@ + > @TOH "ToricVectorBundles :: ToricVectorBundles"@ + > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ + :Core topics + > "singularLocus" + > "Grassmannian" + > "Schubert" + > "Fano" + > "isNormal" + > "isSmooth" + > "genus" + Text + The reference links below remain available for direct access to core geometry commands. + SeeAlso + "packages provided with Macaulay2" + "Varieties :: Varieties" + "Schubert2 :: Schubert2" + "NormalToricVarieties :: NormalToricVarieties" + "CharacteristicClasses :: CharacteristicClasses" + "HyperplaneArrangements :: HyperplaneArrangements" + "RationalPoints :: RationalPoints" + "ToricVectorBundles :: ToricVectorBundles" Subnodes singularLocus Grassmannian @@ -112,9 +306,93 @@ Node genus genera +Node + Key + "Representation Theory" + Description + Text + Representation theory in Macaulay2 currently centers on symmetric + functions, Schur and Weyl functors, root systems, Weyl groups, and + related character computations. + Tree + :Selected Packages + > @TOH "SchurRings :: SchurRings"@ + > @TOH "SchurFunctors :: SchurFunctors"@ + > @TOH "PieriMaps::PieriMaps"@ + > @TOH "WeylGroups :: WeylGroups"@ + > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ + :Core topics + > @TOH "SchurFunctors :: schur"@ + > @TOH "SchurFunctors :: schurModule"@ + > @TOH "SchurRings :: plethysm"@ + > @TOH "SchurRings :: internalProduct"@ + > @TOH "WeylGroups :: rootSystem"@ + > @TOH "WeylGroups :: dynkinType"@ + > @TOH "WeylGroups :: cartanMatrix"@ + Text + The reference links below remain available for direct access to package + entry points and core constructions. + SeeAlso + "packages provided with Macaulay2" + "SchurRings :: SchurRings" + "SchurFunctors :: SchurFunctors" + "PieriMaps::PieriMaps" + "WeylGroups :: WeylGroups" + Subnodes + @TO "SchurRings :: SchurRings"@ + @TO "SchurFunctors :: SchurFunctors"@ + @TO "PieriMaps::PieriMaps"@ + @TO "WeylGroups :: WeylGroups"@ + "SchurFunctors :: schur" + "SchurFunctors :: schurModule" + "SchurRings :: plethysm" + "SchurRings :: internalProduct" + "WeylGroups :: rootSystem" + "WeylGroups :: dynkinType" + "WeylGroups :: cartanMatrix" + Node Key "combinatorics" + Description + Text + Combinatorics in Macaulay2 spans graphs, posets, simplicial complexes, + polyhedra, lattice polytopes, and combinatorial commutative algebra. + Tree + :Selected Packages + > @TOH "Graphs :: Graphs"@ + > @TOH "Posets :: Posets"@ + > @TOH "Matroids :: Matroids"@ + > @TOH "EdgeIdeals :: EdgeIdeals"@ + > @TOH "SimplicialComplexes :: SimplicialComplexes"@ + > @TOH "Polyhedra :: Polyhedra"@ + > @TOH "LatticePolytopes :: LatticePolytopes"@ + > @TOH "StatePolytope :: StatePolytope"@ + > @TOH "Nauty :: Nauty"@ + > @TOH "NautyGraphs :: NautyGraphs"@ + > @TOH "FourTiTwo :: FourTiTwo"@ + > @TOH "Normaliz :: Normaliz"@ + > @TOH "SimplicialDecomposability :: SimplicialDecomposability"@ + > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ + :Core topics + > "partitions" + > "compositions" + > "binomial" + > "Set" + > "cone" + > "rays" + > "normalCone" + > "multidegree" + SeeAlso + "packages provided with Macaulay2" + "Graphs :: Graphs" + "Posets :: Posets" + "EdgeIdeals :: EdgeIdeals" + "SimplicialComplexes :: SimplicialComplexes" + "Polyhedra :: Polyhedra" + "LatticePolytopes :: LatticePolytopes" + "Nauty :: Nauty" + "FourTiTwo :: FourTiTwo" Subnodes binomial compositions diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_groebner_bases.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_groebner_bases.m2 index 503223b8466..edd496c93ea 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_groebner_bases.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_groebner_bases.m2 @@ -5,6 +5,7 @@ document { Key => "Gröbner bases", + Headline => "an overview of Gröbner basis computations", "A Gröbner basis is a specific generating set for an ideal or submodule, often used to compute other information, such as numerical invariants, operations such as intersections and ideal quotients, syzygies, etc. In Macaulay2, Gröbner bases @@ -117,6 +118,7 @@ document { document { Key => "normal forms", + Headline => "compute normal forms with Gröbner bases", TEX ///Let $R = k[x_1, ..., x_n]$ be a polynomial ring over a field k, and let $I \subset{} R$ be an ideal. Let $\{g_1, ..., g_t\}$ be a Gröbner basis for $I$. For any $f \in{} R$, there is a unique `remainder' $r \in{} R$ such @@ -141,6 +143,7 @@ document { -- needsPackage "Elimination" document { Key => "elimination of variables", + Headline => "eliminate variables with Gröbner bases", TEX "Let's consider the problem of finding the polynomial relation of the three polynomials $x = s^3+st+1$, $y = t^3+3t^2+t$, and $z = st^3$. The first method we use is to compute a Gröbner basis using an elimination diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 index 47f23518b5b..e19745c1364 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 @@ -11,20 +11,37 @@ Node IMG ("src" => replace("PKG", "Style", currentLayout#"package") | "9planets.gif", "alt" => "image of nine planets") Text Macaulay2 is an interpreted, dynamically typed programming language designed to - support research in commutative algebra, algebraic geometry and related fields. - All components of the language are open sourced, including over two hundred - contributed packages, and generously funded by the National Science Foundation. + support research in commutative algebra, algebraic geometry, and related fields. + This documentation includes getting-started guides, language and reference material, + tutorials, and package documentation for the packages distributed with Macaulay2. + Text + If you are new to Macaulay2, start with the setup notes and a first Macaulay2 + session. If you know the mathematics you want to do but not yet the command or + package name, browse the sections on practical guides, mathematical objects, + computations, and packages. Tree :Getting Started > "setting up Macaulay2" > "a first Macaulay2 session" > "reading the documentation" > "getting help or reporting bugs" - -- TODO: "contributing to Macaulay2" - -- Macaulay2 is an open source project, and we welcome programming contributions of all kinds. - :Reference Manual + :Practical Guides > "The Macaulay2 language" - > "packages provided with Macaulay2" + > @TO2("packages", "loading and using packages")@ + > @TO2("packages provided with Macaulay2", "browsing packages by subject area")@ + > "debugging" + > "the debugger" + > "error handling" + :Mathematical Tutorials + -- These tutorials begin with broader introductions and continue with + -- more specialized worked examples in algebra and geometry. + > "A first course in commutative algebra" + > "Tutorial: Modules in Macaulay2" + > "Tutorial: Elementary uses of Gröbner bases" + > "Tutorial: Divisors" + > "Tutorial: Canonical Embeddings of Plane Curves and Gonality" + > "Tutorial: Fano varieties" + > "Tutorial: Numerical algebraic geometry" :Mathematical Objects > "rings" > "ideals" @@ -33,27 +50,19 @@ Node > @TO2(map, "morphisms")@ > @TO2("Complexes :: Complexes", "chain complexes")@ (also see @TO2("OldChainComplexes :: OldChainComplexes", "legacy version")@) > @TO2("Varieties :: Varieties", "varieties and sheaves")@ - :Mathematical Tutorials - -- In this section we present some tutorials that aim to introduce - -- the user to some mathematical ways of using Macaulay2. The tutorials - -- are relatively independent of each other, and each one introduces the use - -- of some features of Macaulay2 in a slow and leisurely way, assuming the - -- reader is already familiar with the mathematical concepts involved. - -- -- @TO "David Eisenbud"@ joins us as a co-author of these tutorials. - > "A first course in commutative algebra" - > "Tutorial: Modules in Macaulay2" - > "Tutorial: Elementary uses of Gröbner bases" - > "Tutorial: Canonical Embeddings of Plane Curves and Gonality" - > "Tutorial: Fano varieties" - > "Tutorial: Divisors" - > "Tutorial: Numerical algebraic geometry" + > @TO2("Graphs :: Graphs", "graphs")@ + > @TO2("Posets :: Posets", "posets")@ + > @TO2("SimplicialComplexes :: SimplicialComplexes", "simplicial complexes")@ + > @TO2("Polyhedra :: Polyhedra", "polyhedra")@ :Mathematical Computations - > "elementary arithmetic" - > "commutative algebra" - > "homological algebra" - > "algebraic geometry" - > "combinatorics" - > "analytic functions" + > @TO2("elementary arithmetic", "Elementary Arithmetic")@ + > @TO2("linear algebra", "Linear Algebra")@ + > @TO2("commutative algebra", "Commutative Algebra")@ + > @TO2("homological algebra", "Homological Algebra")@ + > @TO2("algebraic geometry", "Algebraic Geometry")@ + > "Representation Theory" + > @TO2("combinatorics", "Combinatorics")@ + > @TO2("analytic functions", "Analytic Functions")@ Tree :Appendix > "changes to Macaulay2, by version" @@ -62,47 +71,18 @@ Node Acknowledgement Tree > "Acknowledgements" - > "Copyright and license" - Contributors - Tree > "The authors of Macaulay2" > "The authors of Macaulay2 packages" - - The contributors of Macaulay2 documentation: - - Daniel Grayson - - Michael Stillman - - Mahrud Sayrafi - - Doug Torrance - - Paul Zinn-Justin - - Lily Silverstein - - Frédéric Chapoton - - Zach Teitler - - Anton Leykin - - Guillem Blanco - - Dave Barton - - Brian Pike - - Michael Burr - - Frank Moore - - Fatemeh Tarashi - - Dylan Peifer - - Thomas Kahle - - Marc Harkonen - - David Eisenbud - - Boyana Martinova - - Eliana Duarte - - Lars Kastner - - Kisun Lee - -- the following contributors don't appear in git history - -- but have been credited in various documentation files. - - Sorin Popescu - - Manoj Kummini - - Leah Gold - - Amelia Taylor - - Giulio Caviglia - - Gregory G. Smith - - Wolfram Decker - - Jonah Blasiak - - Josephine Yu - - Irena Peeva + > "Copyright and license" + Contributors + Contributors to Macaulay2 documentation include Daniel Grayson, Michael Stillman, + Mahrud Sayrafi, Doug Torrance, Paul Zinn-Justin, Lily Silverstein, Frédéric Chapoton, + Zach Teitler, Anton Leykin, Guillem Blanco, Dave Barton, Brian Pike, Michael Burr, + Frank Moore, Fatemeh Tarashi, Dylan Peifer, Thomas Kahle, Marc Harkonen, David Eisenbud, + Boyana Martinova, Eliana Duarte, Lars Kastner, and Kisun Lee; additional names credited + in documentation files outside git history include Sorin Popescu, Manoj Kummini, + Leah Gold, Amelia Taylor, Giulio Caviglia, Gregory G. Smith, Wolfram Decker, + Jonah Blasiak, Josephine Yu, and Irena Peeva. References -- TODO: node to be written, will point to our book, Hal's book, Mike's Arizona notes, Sage, etc: @UL { diff --git a/M2/Macaulay2/packages/Macaulay2Doc/shared.m2 b/M2/Macaulay2/packages/Macaulay2Doc/shared.m2 index badf8b9f551..2930b90c9ef 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/shared.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/shared.m2 @@ -19,7 +19,7 @@ document { Key => extend, Headline => "extend an object", methodstr, document { Key => complete, methodstr, SeeAlso => { "OldChainComplexes::complete(ChainComplex)" } } document { Key => minimize, methodstr, SeeAlso => { "Complexes::minimize(Complex)" } } -document { Key => decompose, methodstr, SeeAlso => { "MinimalPrimes::MinimalPrimes" } } +document { Key => decompose, Headline => "decompose an object", methodstr, SeeAlso => { "MinimalPrimes::MinimalPrimes" } } document { Key => truncate, methodstr, SeeAlso => { "Truncations::Truncations" } } document { Key => chi, methodstr, SeeAlso => { "Schubert2::chi(AbstractSheaf)", "NormalToricVarieties::chi(CoherentSheaf)" } } @@ -29,11 +29,11 @@ document { Key => euler, methodstr, SeeAlso => { "Schubert2::euler(AbstractVariety)", "Varieties::Varieties" } } document { Key => eulers, methodstr } document { Key => genera, methodstr } -document { Key => genus, methodstr } -document { Key => isExact, methodstr, SeeAlso => { +document { Key => genus, Headline => "genus of an object", methodstr } +document { Key => isExact, Headline => "whether an object is exact", methodstr, SeeAlso => { "ChainComplexExtras :: isExact(ChainComplex)", "Complexes :: isExact(Complex)" } } -document { Key => isSmooth, methodstr, SeeAlso => { +document { Key => isSmooth, Headline => "whether an object is smooth", methodstr, SeeAlso => { "WeilDivisors::isSmooth(Ideal)", "LatticePolytopes::isSmooth(Polyhedron)", "Varieties::isSmooth(Variety)", "SpaceCurves::isSmooth(Curve)", "Polyhedra::isSmooth(Cone)", "NormalToricVarieties::isSmooth(NormalToricVariety)", @@ -42,12 +42,12 @@ document { Key => isVeryAmple, methodstr, SeeAlso => { "WeilDivisors::isVeryAmple(WeilDivisor)", "Polyhedra::isVeryAmple(Polyhedron)", "PositivityToricBundles::isVeryAmple(ToricVectorBundleKlyachko)", "NormalToricVarieties::isVeryAmple(ToricDivisor)" } } -document { Key => isNormal, methodstr, SeeAlso => { +document { Key => isNormal, Headline => "whether an object is normal", methodstr, SeeAlso => { "Polyhedra::isNormal(Polyhedron)", "IntegralClosure::isNormal(Ring)", "AssociativeAlgebras::isNormal(RingElement)", } } -document { Key => normalCone, methodstr, SeeAlso => { +document { Key => normalCone, Headline => "normal cone of an object", methodstr, SeeAlso => { "Polyhedra::normalCone(Polyhedron,Polyhedron)", "ReesAlgebra::normalCone(Ideal)", } } From 91520509783dd065144be0255b0f30aca2b2cf18 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Tue, 19 May 2026 14:19:38 -0400 Subject: [PATCH 44/73] docs: add package landing examples for refresh issues --- M2/Macaulay2/packages/Pullback.m2 | 14 ++++++++-- M2/Macaulay2/packages/PushForward.m2 | 28 +++++++++++++++++++- M2/Macaulay2/packages/QthPower.m2 | 15 ++++++++--- M2/Macaulay2/packages/Quasidegrees.m2 | 14 +++++++++- M2/Macaulay2/packages/RandomGenus14Curves.m2 | 12 +++++++++ 5 files changed, 76 insertions(+), 7 deletions(-) diff --git a/M2/Macaulay2/packages/Pullback.m2 b/M2/Macaulay2/packages/Pullback.m2 index 616dacc8acd..fa1773e2225 100644 --- a/M2/Macaulay2/packages/Pullback.m2 +++ b/M2/Macaulay2/packages/Pullback.m2 @@ -395,7 +395,18 @@ document{ Key => Pullback, Headline => "pullback in the category of rings", EM "Pullback", " is a package that implements pullback for diagrams of rings", - Caveat => "Works only for maps of rings finitely generated over a base field and one of the two maps is surjective" + TEX "Start with two maps to a common quotient ring and compute the resulting pullback ring.", + EXAMPLE lines /// + A = QQ[x]; + B = A/ideal(x); + C = QQ[y]; + f = map(B, A); + g = map(B, C, {0}); + R = (pullback(f,g))#0; + (dim R, numgens ideal R) + ///, + Caveat => "Works only for maps of rings finitely generated over a base field and one of the two maps is surjective", + SeeAlso => {"Pullback::pullback(RingMap,RingMap)"} } document{ @@ -551,4 +562,3 @@ end --1.01, added support for C with no variables. Improved documentation. Turned off some printed text when Verbose is turned off. --1.02, improved documentation including adding documentation for the product of rings. --1.03, improved error reporting so that it provides useful information about the problem is - diff --git a/M2/Macaulay2/packages/PushForward.m2 b/M2/Macaulay2/packages/PushForward.m2 index bdd385206c9..15a59d1b99a 100644 --- a/M2/Macaulay2/packages/PushForward.m2 +++ b/M2/Macaulay2/packages/PushForward.m2 @@ -296,10 +296,23 @@ doc /// This package was originally implemented by Claudiu Raicu, some changes were introduced by Karl Schwede, and later by David Eisenbud and Mike Stillman. + Text + Start with a finite ring map and a module over the target ring. + Example + kk = QQ; + T = kk[t]; + S = kk[a,b]/ideal(a*b); + use S; + M = module ideal(a); + phi = map(S,T,{a}); + pushFwd(phi, M) Subnodes (pushFwd, RingMap) (pushFwd, RingMap, Module) (pushFwd, RingMap, Matrix) + SeeAlso + pushFwd + isModuleFinite /// doc /// @@ -445,11 +458,24 @@ document{ Key => pushFwd, Headline => "push forward", "The push forward functor", + PARA { + "Start with a finite ring map and a module over the target ring." + }, + EXAMPLE lines /// + kk = QQ; + T = kk[t]; + S = kk[a,b]/ideal(a*b); + use S; + M = module ideal(a); + phi = map(S,T,{a}); + pushFwd(phi, M) + ///, UL { {TO (pushFwd,RingMap)," - for a finite ring map"}, {TO (pushFwd,RingMap,Module), " - for a module"}, {TO (pushFwd,RingMap,Matrix), " - for a map of modules"} - } + }, + SeeAlso => {(pushFwd,RingMap),(pushFwd,RingMap,Module),(pushFwd,RingMap,Matrix),isModuleFinite} } -- document{ diff --git a/M2/Macaulay2/packages/QthPower.m2 b/M2/Macaulay2/packages/QthPower.m2 index 13475f8b1d8..828db3fb2fd 100644 --- a/M2/Macaulay2/packages/QthPower.m2 +++ b/M2/Macaulay2/packages/QthPower.m2 @@ -960,7 +960,18 @@ document { Also this package contains the extension to examples over the rationals; which, in turn, allows for quicker answers over ZZ/q for most large q, which can be produced if desired merely by changing the coefficient ring from QQ to ZZ/q." - } + }, + PARA { + "Start with a small finite-field example to compute an integral closure and inspect the size of the returned presentation." + }, + EXAMPLE lines /// + wtR = matrix{{5,6,6},{3,6,0}}; + Rq = ZZ/23[u,v,w,Weights=>entries weightGrevlex(wtR)]; + GB = {u^6+u^3*w-v^3*w^2}; + (numerators,relicR,icR,wticR) = qthIntegralClosure(wtR,Rq,GB); + (#numerators, numgens ideal relicR) + ///, + SeeAlso => {qthIntegralClosure, rationalIntegralClosure, qthConductor, weightGrevlex} } -------------------------------------------------------------------------------------------------------- document { @@ -1398,8 +1409,6 @@ wtR13 = matrix{{25,21}}; - - diff --git a/M2/Macaulay2/packages/Quasidegrees.m2 b/M2/Macaulay2/packages/Quasidegrees.m2 index ebeef73b147..ac033ac0eb1 100644 --- a/M2/Macaulay2/packages/Quasidegrees.m2 +++ b/M2/Macaulay2/packages/Quasidegrees.m2 @@ -428,12 +428,25 @@ doc /// hypergeometric families}. J. Am. Math. Soc., 18(4):919-941, 2005. This package requires @TO FourTiTwo@, @TO Depth@, and @TO Polyhedra@. + Text + Start with a small multigraded module and compute its quasidegree set directly. + Example + A = matrix{{1,0},{0,1}} + R = QQ[x,y, Degrees => entries transpose A] + I = ideal(x^2,y^2) + M = R^1/I + quasidegrees M Caveat This package is written when the ambient ring of the modules in question are positively graded and are presented by a monomial matrix, that is, a matrix whose entries are monomials. This is due to the algorithms depending on finding standard pairs of monomial ideals generated by rows of a presentation matrix. + SeeAlso + makeGradedRing + toGradedRing + quasidegrees + quasidegreesLocalCohomology /// ----------------------------------- @@ -898,4 +911,3 @@ restart installPackage"Quasidegrees" check "Quasidegrees" needsPackage"Quasidegrees" - diff --git a/M2/Macaulay2/packages/RandomGenus14Curves.m2 b/M2/Macaulay2/packages/RandomGenus14Curves.m2 index f1e2b2234fd..624b1b83f7a 100644 --- a/M2/Macaulay2/packages/RandomGenus14Curves.m2 +++ b/M2/Macaulay2/packages/RandomGenus14Curves.m2 @@ -176,6 +176,18 @@ doc /// \ \ \ \ \ [Mu] S. Mukai, Curves, $K3$ surfaces and Fano $3$-folds of genus $\leq 10$. Algebraic geometry and commutative algebra, Vol. I, 357-377, Kinokuniya, Tokyo, 1988. \ \ \ \ \ [Ve] A. Verra, The unirationality of the moduli spaces of curves of genus 14 or lower. Compos. Math. 141 (2005), no. 6, 1425-1444. + Text + The example below starts with a homogeneous coordinate ring of $\PP^6$ over a finite field and constructs a genus 14 curve of degree 18. + Example + setRandomSeed("alpha"); + FF = ZZ/10007; + S = FF[u_0..u_6]; + I = randomCurveGenus14Degree18inP6 S; + (dim I, degree I, genus I) + SeeAlso + canonicalCurveGenus14 + curveGenus14Degree18inP6 + randomCanonicalCurveGenus8with8Points /// doc /// From 4b4af28c1381835a11dd763f2229d5f15fa51b5c Mon Sep 17 00:00:00 2001 From: klee669 Date: Tue, 19 May 2026 14:52:43 -0400 Subject: [PATCH 45/73] Update tu_NAG.m2 Updated NAG tutorial (based on Taylor's suggestions). --- M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 | 67 +++++++++++++++++--- 1 file changed, 59 insertions(+), 8 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 b/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 index 8d41ac153c1..7e2dafbf1e9 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 @@ -6,13 +6,32 @@ Node Numerical algebraic geometry Description Text + @BOLD "Quick start: Solving a system of equations"@ + + Suppose that you would like to solve a system of polynomial equations (polynomial system). + Using Macaulay2, one can simply run the following: + + Example + needsPackage "NumericalAlgebraicGeometry" + R = CC[x,y]; + f = {x^2+y^2-2, (x-2)^2-y^2-6}; -- your system of interest + solveSystem f + + Text + The system $f$ describes the intersection of a circle and a hyperbola, + and therefore has four intersection points over the complex numbers. + + Solving polynomial systems is a central problem in algebraic geometry, + with many applications in areas such as engineering and scientific computing. + {\it Numerical algebraic geometry} uses techniques from numerical analysis - to study and approximate solutions of systems of polynomial equations. + to find (approximate) solutions of systems of polynomial equations. Traditionally, polynomial systems are studied using symbolic methods - such as Gr\"obner bases, resultants, and elimination techniques. + such as Gröbner bases, resultants, and elimination techniques. While these methods are powerful, they often become prohibitively slow for large or complicated systems. + Numerical algebraic geometry provides an alternative by replacing exact symbolic computations with high-precision numerical approximations. @@ -44,22 +63,31 @@ Node R = CC[x,y] g = {x^2-1,y^2-1} f = {x^2+y^2-1, (x-y)^2-1} - solsS = {(1,-1),(1,1),(-1,1),(-1,-1)} + solsS = {(1,-1),(1,1),(-1,1),(-1,-1)} -- solutions to g track(g,f,solsS) Text - In this example, the start system is a {\it B\'ezout start system}, + In this example, the start system is a {\it Bézout start system}, giving a total number of paths equal to the product of the degrees of the defining polynomials. This number is an upper bound for the number of isolated solutions of the target system. - The same computation can also be carried out using: + The same process can also simply be carried out using: Example R = CC[x,y]; f = {x^2+y^2-1, (x-y)^2-1}; solveSystem f + Text + Note that homotopy continuation techniques are typically applied to + zero-dimensional systems, that is, systems with finitely many solutions. + + This often occurs when the system has the same number of equations + as variables and the equations are sufficiently generic, + yielding a complete intersection. + + Text @BOLD "B. Witness sets and numerical irreducible decomposition"@ @@ -89,7 +117,8 @@ Node (x^2+y^2+z^2-1)*(z-x^3) }; W = components numericalIrreducibleDecomposition I - sample first W + p = sample first W -- sampling a point from the first component + evaluate(gens I, p) Text @BOLD "C. Monodromy methods"@ @@ -117,7 +146,6 @@ Node Example needsPackage "MonodromySolver" - setRandomSeed 0; declareVariable \ {A,B,C,D,X,Y}; F = gateSystem( matrix{{A,B,C,D}}, @@ -209,7 +237,30 @@ Node q = first numericalImageSample(F, I) -- sampling a point from the variety isOnImage(F, I, q, Verbose => false) - Text + Some references for numerical algebraic geometry: + + * Andrew J. Sommese, and Charles W. Wampler. "The Numerical solution of systems of polynomials arising in engineering and science." {\it World Scientific} (2005)., + + * Anton Leykin. "Numerical algebraic geometry" {\it Journal of Software for Algebra and Geometry} 3(1) (2011): 5-10., + + * Timothy Duff, Cvetelina Hill, Anders Jensen, Kisun Lee, Anton Leykin, and Jeff Sommars. "Solving polynomial systems via homotopy continuation and monodromy." {\it IMA Journal of Numerical Analysis} 39.3 (2019): 1421-1446., + + * Jonathan D. Hauenstein, and Frank Sottile "Algorithm 921: alphaCertified: certifying solutions to polynomial systems" {\it ACM Transactions on Mathematical Software (TOMS)} 38.4 (2012): 1-20., + + * Michael Burr, Kisun Lee, and Anton Leykin. "Effective certification of approximate solutions to systems of equations involving analytic functions." {\it Proceedings of the 2019 International Symposium on Symbolic and Algebraic Computation}. (2019): 267-274., + + * Justin Chen, and Joe Kileel. "Numerical implicitization." {\it Journal of Software for Algebra and Geometry} 9.1 (2019): 55-63. + + + + This tutorial is written by Kisun Lee. + + SeeAlso + "NumericalAlgebraicGeometry" + "MonodromySolver" + "NumericalCertification" + "NumericalImplicitization" + /// From 4c0401faf6cdca4d49371c73bfa5c1b15b2cbeb8 Mon Sep 17 00:00:00 2001 From: David Eisenbud Date: Mon, 18 May 2026 15:19:35 -0400 Subject: [PATCH 46/73] documented (map, GaloisField, GaloisField) --- .../Macaulay2Doc/functions/map-doc.m2 | 40 +++++++++++++++++-- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 index 175dc570d33..bb8af3e14fb 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 @@ -2,10 +2,42 @@ --- author(s): --- notes: --* --- TODO -(map,GaloisField,GaloisField) -*- +doc /// +Node + Key + (map, GaloisField, GaloisField, List) + (map, GaloisField, GaloisField) + Headline + maps of Galois fields + Usage + phi = map(F,G) + phi = map(F,G,x) + Inputs + F:GaloisField + G:GaloisField + x:List + one element of F generating a subfield isomorphic to G + Outputs + phi:RingMap + carrying 1 to x + Description + Text + GF(p^n) contains GF(p^m) if and only if m divides n + Example + F4 = GF(2^2) + F8 = GF(2^3) + F16 = GF(2^4) + map(F16, F4) + map(F16, F8) + Text + It is possible to "define a map" that is not well-defined: + Example + phi = map(F16, F4, {1}) + isWellDefined phi + SeeAlso + isWellDefined + GF +/// undocumented {(map, RingFamily, Thing, Thing),(map, Thing, RingFamily, Thing), (map, RingFamily, Thing), (map, Thing, RingFamily)} From 1e2ed3b998790ade66618daa89027b38e30f1138 Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Tue, 19 May 2026 08:51:33 -0400 Subject: [PATCH 47/73] add examples and docs for kernel method --- .../Macaulay2Doc/functions/kernel-doc.m2 | 190 +++++++++++------- 1 file changed, 116 insertions(+), 74 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 index 675a84e84b7..78ed65ccb5e 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 @@ -1,13 +1,3 @@ --- -*- coding: utf-8 -*- ---- status: TODO ---- author(s): ---- notes: - -undocumented { - [kernel, DegreeLimit], - [kernel, Strategy], -} - doc /// Node Key @@ -25,70 +15,122 @@ Node syz /// -document { - Key => (kernel,RingMap), - Headline => "kernel of a ringmap", - Usage => "kernel f", - Inputs => { - "f" => {TT "R", " --> ", TT "S"}, - SubringLimit => ZZ => "stop the computation after this many elements of the kernel have been found" - }, - Outputs => { - Ideal => {"an ideal of ", TT "R"} - }, - EXAMPLE lines /// - R = QQ[a..d]; - S = QQ[s,t]; - F = map(S,R,{s^3, s^2*t, s*t^2, t^3}) - ker F - G = map(S,R,{s^5, s^3*t^2-t, s*t-s, t^5}) - ker(G, SubringLimit=>1) - ///, - "In the case when everything is homogeneous, Hilbert functions are - used to speed up the computations.", - Caveat => {"It should be possible to interrupt the computation and restart it, but this has - not yet been implemented."}, - SeeAlso => {"substitution and maps between rings", "elimination of variables", monomialCurveIdeal}, - Subnodes => { TO [kernel, SubringLimit] }, - } - -document { - Key => {(kernel,Matrix), - (kernel, RingElement)}, - Headline => "kernel of a map of modules", - Usage => "kernel f, kernel a", - Inputs => { - "f" => {"a map of modules ", TT "M --> N"} - }, - Outputs => { - Module => {"the kernel of f, a submodule of M"} - }, - PARA{}, - "The kernel is the submodule of M of all elements mapping to zero under ", TT "f", ".", - "If f is a RingElement it is interpreted as a 1 by 1 matrix",".", - EXAMPLE lines /// - R = ZZ/32003[a,b]/(ideal(a,b))^3 - M = R^1/(ideal a^2) - mat = matrix{{a^2,b^2},{b,a}} - ker mat - presentation ker mat - syz mat - f = map(M++M, M++M, mat) - ker f - ///, - SeeAlso => {syz, - cokernel, - image, - map, - matrix - } - } - +doc /// + Key + (kernel, RingMap) + Headline + kernel of a ringmap + Usage + kernel f + Inputs + f:RingMap + $f: R \rightarrow S$ + SubringLimit => ZZ + stop the computation after this many elements of the kernel have been found. + DegreeLimit => ZZ + stop the computation after generators for the kernel in this degree have been found + Strategy => String + Groebner basis computation strategy. See @TO gb@. + Outputs + :Ideal + an ideal of $R$ + Description + Text + The twisted cubic. + Example + R = QQ[a..d]; + S = QQ[s,t]; + -- F = map(S,R,{s^3, s^2*t, s*t^2, t^3}) + -- ker F + Text + Passing @TT "SubringLimit"@ stops the computation early. + Example + R = QQ[a..d]; + -- S = QQ[s,t]; + -- F = map(S,R,{s^3, s^2*t, s*t^2, t^3}) + -- ker(F, SubringLimit => 1) + Text + In the case when everything is homogeneous, Hilbert functions are used to speed up the computations. + Caveat + It should be possible to interrupt the computation and restart it, but this has not yet been implemented. + SeeAlso + "substitution and maps between rings" + "elimination of variables" + monomialCurveIdeal + Subnodes + kernel + SubringLimit + DegreeLimit + Strategy +/// document { - Key => [kernel, SubringLimit], - Headline => "stop after finding enough elements of a subring", - TT "SubringLimit => n", " -- an option for ", TO "kernel", " which - causes the computation of the kernel of a ring map to stop after ", TT "n", " - elements have been discovered." + Key => {(kernel,Matrix), + (kernel, RingElement)}, + Headline => "kernel of a map of modules", + Usage => "kernel f, kernel a", + Inputs => { + "f" => {"a map of modules ", TT "M --> N"} + }, + Outputs => { + Module => {"the kernel of f, a submodule of M"} + }, + PARA{}, + "The kernel is the submodule of M of all elements mapping to zero under ", TT "f", ".", + "If f is a RingElement it is interpreted as a 1 by 1 matrix",".", + EXAMPLE lines /// + R = ZZ/32003[a,b]/(ideal(a,b))^3 + M = R^1/(ideal a^2) + mat = matrix{{a^2,b^2},{b,a}} + ker mat + presentation ker mat + syz mat + f = map(M++M, M++M, mat) + ker f + ///, + SeeAlso => { + syz, + cokernel, + image, + map, + matrix + } } + +doc /// +Key + [kernel, SubringLimit] +Headline + stop after finding enough elements of a subring +Description + Text + @TT "SubringLimit => n"@ -- an option for @TO kernel@ which + causes the computation of the kernel of a ring map to stop after @TT "n"@ + elements have been discovered." +/// + + +doc /// +Key + [kernel, DegreeLimit] +Headline + stop after finding enough elements of a subring +Description + Text + @TT "DegreeLimit => n"@ -- an option for @TO kernel@ which + causes the computation of the kernel of a ring map to stop after generators for the degree @TT "n"@ + part of the kernel have been discovered." +/// + + +doc /// +Key + [kernel, Strategy] +Headline + strategy for Groebner Basis computations used in kernel computations +Description + Text + This option is passed through to @TO gb@ when computing the kernel of a @TT "RingMap"@. +SeeAlso + gb +/// From 0167253ceeb73fbca8c076bd8987ddcd653b1946 Mon Sep 17 00:00:00 2001 From: David Eisenbud Date: Tue, 19 May 2026 10:36:28 -0400 Subject: [PATCH 48/73] forceGB-doc and gb-doc minor updates --- M2/Macaulay2/packages/Macaulay2Doc/functions/forceGB-doc.m2 | 2 +- M2/Macaulay2/packages/Macaulay2Doc/functions/gb-doc.m2 | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/forceGB-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/forceGB-doc.m2 index 5da43d61ff7..8fb09854d7c 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/forceGB-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/forceGB-doc.m2 @@ -33,7 +33,7 @@ document { "gens gb f" }, PARA { - "If an autoreduced Gröbner basis is desired, replace ", TT "f", " by ", TT "gens forceGB f", " first." + "If an autoreduced Gröbner basis (not just the Groebner basis object) is desired, replace ", TT "forceGB f", " by ", TT "gens forceGB f", "." }, Caveat => {"If the columns do not form a Gröbner basis, nonsensical answers may result"}, SeeAlso => {"Gröbner bases"}, diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/gb-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/gb-doc.m2 index 611810d134e..58d3dfec1d8 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/gb-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/gb-doc.m2 @@ -3,8 +3,6 @@ --- author(s): --- notes: -undocumented (NewFromMethod, GroebnerBasis, Matrix, GroebnerBasisOptions, OptionTable) - document { Key => {gb, (gb,Ideal), From 94cc57a61092177a2192167a87970f452b6ce686 Mon Sep 17 00:00:00 2001 From: klee669 Date: Tue, 19 May 2026 14:54:00 -0400 Subject: [PATCH 49/73] Update tu_NAG.m2 --- M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 b/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 index 7e2dafbf1e9..e2f5379f4a0 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 @@ -150,7 +150,7 @@ Node F = gateSystem( matrix{{A,B,C,D}}, matrix{{X,Y}}, - matrix{{A*(X-1)^2-B}, {C*(Y+2)^2+D}} + matrix{{A*(X-1)^2+B}, {C*(Y+2)^2+D}} ); -- Define a parameter system with parameters A,B,C,D in variables X,Y p0 = point{{1,1,1,1}}; -- a parameter point sols = solveFamily(p0, F, NumberOfNodes=>3) -- 4 solutions for a fixed parameter p0 From ce049e079e761c5ff0191afa839f365e27bf2335 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Mon, 18 May 2026 10:50:36 -0400 Subject: [PATCH 50/73] Expand representation theory documentation overview --- .../packages/Macaulay2Doc/ov_examples.m2 | 27 +++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 index 2d57ce22eb4..57c13958e5e 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 @@ -312,20 +312,31 @@ Node Description Text Representation theory in Macaulay2 currently centers on symmetric - functions, Schur and Weyl functors, root systems, Weyl groups, and - related character computations. + functions, Schur and Weyl functors, Lie algebras and their + representations, highest-weight methods, group actions, invariant + theory, and related character computations. Tree :Selected Packages > @TOH "SchurRings :: SchurRings"@ > @TOH "SchurFunctors :: SchurFunctors"@ > @TOH "PieriMaps::PieriMaps"@ > @TOH "WeylGroups :: WeylGroups"@ + > @TOH "LieAlgebraRepresentations :: LieAlgebraRepresentations"@ + > @TOH "GradedLieAlgebras :: GradedLieAlgebras"@ + > @TOH "HighestWeights :: HighestWeights"@ + > @TOH "InvariantRing :: InvariantRing"@ + > @TOH "BettiCharacters :: BettiCharacters"@ > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ :Core topics > @TOH "SchurFunctors :: schur"@ > @TOH "SchurFunctors :: schurModule"@ > @TOH "SchurRings :: plethysm"@ > @TOH "SchurRings :: internalProduct"@ + > @TOH "LieAlgebraRepresentations :: simpleLieAlgebra"@ + > @TOH "HighestWeights :: setWeights"@ + > @TO2("HighestWeights :: HighestWeights", "highest-weight decompositions")@ + > @TO2("InvariantRing :: InvariantRing", "group actions and invariant rings")@ + > @TO2("BettiCharacters :: BettiCharacters", "characters on resolutions and graded modules")@ > @TOH "WeylGroups :: rootSystem"@ > @TOH "WeylGroups :: dynkinType"@ > @TOH "WeylGroups :: cartanMatrix"@ @@ -338,15 +349,27 @@ Node "SchurFunctors :: SchurFunctors" "PieriMaps::PieriMaps" "WeylGroups :: WeylGroups" + "LieAlgebraRepresentations :: LieAlgebraRepresentations" + "GradedLieAlgebras :: GradedLieAlgebras" + "HighestWeights :: HighestWeights" + "InvariantRing :: InvariantRing" + "BettiCharacters :: BettiCharacters" Subnodes @TO "SchurRings :: SchurRings"@ @TO "SchurFunctors :: SchurFunctors"@ @TO "PieriMaps::PieriMaps"@ @TO "WeylGroups :: WeylGroups"@ + @TO "LieAlgebraRepresentations :: LieAlgebraRepresentations"@ + @TO "GradedLieAlgebras :: GradedLieAlgebras"@ + @TO "HighestWeights :: HighestWeights"@ + @TO "InvariantRing :: InvariantRing"@ + @TO "BettiCharacters :: BettiCharacters"@ "SchurFunctors :: schur" "SchurFunctors :: schurModule" "SchurRings :: plethysm" "SchurRings :: internalProduct" + "LieAlgebraRepresentations :: simpleLieAlgebra" + "HighestWeights :: setWeights" "WeylGroups :: rootSystem" "WeylGroups :: dynkinType" "WeylGroups :: cartanMatrix" From 4f82b8a951eb7c549b1cf01cc0b7025267ff2ba9 Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Tue, 19 May 2026 10:36:45 -0400 Subject: [PATCH 51/73] uncomment example lines --- .../packages/Macaulay2Doc/functions/kernel-doc.m2 | 10 +++++----- .../packages/Macaulay2Doc/functions/tensor-doc.m2 | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 index 78ed65ccb5e..aad819d9209 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 @@ -40,15 +40,15 @@ doc /// Example R = QQ[a..d]; S = QQ[s,t]; - -- F = map(S,R,{s^3, s^2*t, s*t^2, t^3}) - -- ker F + F = map(S,R,{s^3, s^2*t, s*t^2, t^3}) + ker F Text Passing @TT "SubringLimit"@ stops the computation early. Example R = QQ[a..d]; - -- S = QQ[s,t]; - -- F = map(S,R,{s^3, s^2*t, s*t^2, t^3}) - -- ker(F, SubringLimit => 1) + S = QQ[s,t]; + F = map(S,R,{s^3, s^2*t, s*t^2, t^3}) + ker(F, SubringLimit => 1) Text In the case when everything is homogeneous, Hilbert functions are used to speed up the computations. Caveat diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 index 331a5e656a4..be71b6f811b 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 @@ -470,7 +470,7 @@ doc /// R = kk[a, b, c] I = ideal (a, b); A = I/I^2 J = ideal (b, c); B = J/J^2 - K = ideal (a, c); F = K/K^2 + K = ideal (a, c); C = K/K^2 T = A_0 ** (B_0 ** C_0) T' = (A_0 ** B_0) ** C_0 assert(tensorAssociativity(A, B, C) * T == T') From fc150db438d765de6465ef805441e2f49175e2c8 Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Tue, 19 May 2026 10:46:41 -0400 Subject: [PATCH 52/73] tweak descriptions for optional arguments to kernel --- .../packages/Macaulay2Doc/functions/kernel-doc.m2 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 index aad819d9209..10380a88bce 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 @@ -106,7 +106,7 @@ Description Text @TT "SubringLimit => n"@ -- an option for @TO kernel@ which causes the computation of the kernel of a ring map to stop after @TT "n"@ - elements have been discovered." + elements have been discovered. /// @@ -117,9 +117,9 @@ Headline stop after finding enough elements of a subring Description Text - @TT "DegreeLimit => n"@ -- an option for @TO kernel@ which - causes the computation of the kernel of a ring map to stop after generators for the degree @TT "n"@ - part of the kernel have been discovered." + @TT "DegreeLimit => d"@ -- an option for @TO kernel@ which + causes the computation of the kernel of a ring map to stop after generators for the degree @TT "d"@ + part of the kernel have been discovered. /// From 0c2f91a2cc482272b86206cc9452981102031555 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Tue, 19 May 2026 15:00:17 -0400 Subject: [PATCH 53/73] docs: add examples for package refresh batch --- M2/Macaulay2/packages/NoetherNormalization.m2 | 10 ++- M2/Macaulay2/packages/NumericalSemigroups.m2 | 17 +++-- M2/Macaulay2/packages/PencilsOfQuadrics.m2 | 41 +++++++--- M2/Macaulay2/packages/Points.m2 | 36 +++++++++ M2/Macaulay2/packages/PolyominoIdeals.m2 | 50 +++++++----- M2/Macaulay2/packages/QuillenSuslin.m2 | 25 +++++- M2/Macaulay2/packages/RandomComplexes.m2 | 17 +++++ M2/Macaulay2/packages/SymbolicPowers.m2 | 32 ++++++-- M2/Macaulay2/packages/TSpreadIdeals.m2 | 76 ++++++++++++------- M2/Macaulay2/packages/TerraciniLoci.m2 | 7 ++ 10 files changed, 243 insertions(+), 68 deletions(-) diff --git a/M2/Macaulay2/packages/NoetherNormalization.m2 b/M2/Macaulay2/packages/NoetherNormalization.m2 index 1170572f3f9..83dd06a82f8 100644 --- a/M2/Macaulay2/packages/NoetherNormalization.m2 +++ b/M2/Macaulay2/packages/NoetherNormalization.m2 @@ -229,7 +229,15 @@ document { used are based on algorithms found in A. Logar's paper: A Computational Proof of the Noether Normalization Lemma. In: Proceedings 6th AAEEC, Lecture Notes in Computer Science 357, - Springer, 1989, 259-273." + Springer, 1989, 259-273.", + PARA{}, + "A first example computes a random linear change of coordinates that places an ideal in Noether normal position.", + EXAMPLE lines /// + R = QQ[x_1..x_4]; + I = ideal(x_2^2+x_1*x_2+1, x_1*x_2*x_3*x_4+1); + (f,J,X) = noetherNormalization I + ///, + SeeAlso => {noetherNormalization, LimitList, RandomRange} } ----------------------------------------------------------------------------- diff --git a/M2/Macaulay2/packages/NumericalSemigroups.m2 b/M2/Macaulay2/packages/NumericalSemigroups.m2 index 3ac3e68cf10..3965c5e806a 100644 --- a/M2/Macaulay2/packages/NumericalSemigroups.m2 +++ b/M2/Macaulay2/packages/NumericalSemigroups.m2 @@ -1445,11 +1445,18 @@ Headline => "Compute invariants of a numerical semigroup", The conductor is 1 plus the largest element not in S. We generally specify a semigroup by giving a list of positive integers L with gcd = 1, representing the semigroup of all sums of elements of L.", + PARA{}, + "A quick way to get started is to build the semigroup ring of a small example and inspect a basic invariant.", + EXAMPLE lines /// + L = {3,5,7} + A = semigroupRing(L, "BaseField" => QQ) + isSymmetric L + ///, PARA{}, SUBSECTION "Combinatorial properties of the Kunz cone", UL{ - TO coneEquations, + TO coneEquations, TO mu, TO facetRays, TO coneRays, @@ -1487,9 +1494,10 @@ Headline => "Compute invariants of a numerical semigroup", TO heuristicSmoothness, -- TO isSmoothableSemigroup, TO isWeierstrassSemigroup, - TO nonWeierstrassSemigroups, - TO LabBookProtocol, - } + TO nonWeierstrassSemigroups, + TO LabBookProtocol, + }, + SeeAlso => {semigroupRing, buchweitz, coneEquations} } doc /// @@ -3518,4 +3526,3 @@ tally apply(m,k-> #unique flatten apply(toList(1..m-1),i->(j=(k-i)%m; if j=!=0 18, 24, 25, 26, 28, 30, 33 - diff --git a/M2/Macaulay2/packages/PencilsOfQuadrics.m2 b/M2/Macaulay2/packages/PencilsOfQuadrics.m2 index a9798a2a92c..c922adfeb0b 100644 --- a/M2/Macaulay2/packages/PencilsOfQuadrics.m2 +++ b/M2/Macaulay2/packages/PencilsOfQuadrics.m2 @@ -1699,18 +1699,28 @@ document { which showed that the Kuznetsov component of X and the derived category of E are equivalent by a Fourier-Mukai transformation (see Section 2 of [A. Bondal, D. Orlov, arXiv:alg-geom/9506012], or Section 6 of [A. Bondal, D. Orlov, Proceedings of ICM, Vol. II (Beijing, 2002)]).", - + PARA{}, "We demonstrate this, over finite fields, with the constructions of further random linear spaces on the intersection of two quadrics, and random Ulrich modules of lowest possible rank on the complete intersection of two quadrics for small g.", + PARA{}, + "A first example constructs a random pencil of quadrics and the associated Clifford module over a finite field.", + EXAMPLE { + "kk = ZZ/101;", + "setRandomSeed 0;", + "g = 1;", + "(S,qq,R,u,M1,M2,Mu1,Mu2) = randomNicePencil(kk,g);", + "C = cliffordModule(M1,M2,R);", + "C.hyperellipticBranchEquation" + }, PARA{}, SUBSECTION "Types", UL{ - TO CliffordModule, - TO RandomNicePencil, + TO CliffordModule, + TO RandomNicePencil, TO VectorBundleOnE }, SUBSECTION "Basic Construction of the Clifford Algebra", @@ -2073,12 +2083,19 @@ doc /// Description Text the keys are - oddOperators => uOdd', - evenOperators => uEv', - evenCenter=>c0', - oddCenter => c1', - symmetricM => Q, - hyperellipticBranchEquation => f + oddOperators => uOdd', + evenOperators => uEv', + evenCenter=>c0', + oddCenter => c1', + symmetricM => Q, + hyperellipticBranchEquation => f + Example + kk = ZZ/101 + setRandomSeed 0 + g = 1 + (S, qq, R, u, M1, M2, Mu1, Mu2) = randomNicePencil(kk,g); + C = cliffordModule(M1,M2,R) + C.hyperellipticBranchEquation SeeAlso cliffordModule /// @@ -2638,6 +2655,12 @@ doc /// and a matrix representing the action of y. the only key is yAction + Example + kk = ZZ/101 + R = kk[s,t] + f = (s+2*t)*(s+t)*(s-t)*(s-2*t) + L0 = randomLineBundle(0,f) + (degOnE L0, orderInPic L0) SeeAlso vectorBundleOnE degOnE diff --git a/M2/Macaulay2/packages/Points.m2 b/M2/Macaulay2/packages/Points.m2 index b09577757a0..c1248c1bdae 100644 --- a/M2/Macaulay2/packages/Points.m2 +++ b/M2/Macaulay2/packages/Points.m2 @@ -726,6 +726,15 @@ doc /// In version 3.0, F. Galetto and J.W. Skelton added code to compute ideals of fat points and projective points using the Buchberger-Moeller algorithm. + Example + R = QQ[x,y,z] + M = matrix {{1,0,0,1}, {0,1,0,1}, {0,0,1,1}} + (inG,G) = projectivePoints(M,R) + monomialIdeal G == inG + SeeAlso + randomPointsMat + projectivePoints + projectiveFatPoints /// --documentation for the code for points in projective space @@ -904,6 +913,10 @@ doc /// Text Default is false, in which case the first (up to) r+1 points returned are the standard simplex; if true, all the points are random. + Example + S = ZZ/11[vars(0..2)] + setRandomSeed 0 + randomPointsMat(S,3, AllRandom=>true) SeeAlso randomPointsMat /// @@ -1155,6 +1168,13 @@ doc /// Description Text Default is true, in which case the function removes zero columns and duplicate columns giving rise to the same projective point. + Example + R = QQ[x,y,z] + Mbad = matrix {{1,2,0,1}, {0,0,0,1}, {0,0,0,1}} + Mclean = matrix {{1,1}, {0,1}, {0,1}} + (inG1,G1) = projectivePoints(Mbad,R) + (inG2,G2) = projectivePoints(Mclean,R) + (inG1 == inG2, G1 == G2) SeeAlso projectivePoints /// @@ -1167,6 +1187,13 @@ doc /// Description Text Default is true, in which case the function removes zero columns and duplicate columns giving rise to the same projective point. + Example + R = QQ[x,y,z] + Mbad = matrix {{1,2,0,1}, {0,0,0,1}, {0,0,0,1}} + Mclean = matrix {{1,1}, {0,1}, {0,1}} + (inG1,G1) = projectivePoints(Mbad,R) + (inG2,G2) = projectivePoints(Mclean,R) + (inG1 == inG2, G1 == G2) SeeAlso projectivePoints /// @@ -1180,6 +1207,15 @@ doc /// Text Default is true, in which case the function removes zero columns and duplicate columns giving rise to the same projective point. For duplicate points, a single instance is retained with the largest multiplicity. + Example + R = QQ[x,y,z] + Mbad = matrix {{1,2,0,1}, {0,0,0,1}, {0,0,0,1}} + Mclean = matrix {{1,1}, {0,1}, {0,1}} + mults = {1,3,5,2} + multsClean = {3,2} + (inF1,GF1) = projectiveFatPoints(Mbad,mults,R) + (inF2,GF2) = projectiveFatPoints(Mclean,multsClean,R) + (inF1 == inF2, GF1 == GF2) SeeAlso projectiveFatPoints /// diff --git a/M2/Macaulay2/packages/PolyominoIdeals.m2 b/M2/Macaulay2/packages/PolyominoIdeals.m2 index 8875c3fba59..44a704efe74 100644 --- a/M2/Macaulay2/packages/PolyominoIdeals.m2 +++ b/M2/Macaulay2/packages/PolyominoIdeals.m2 @@ -937,10 +937,10 @@ rankCollection CollectionOfCells := opts -> Q -> ( beginDocumentation() -document { - Key => PolyominoIdeals, - Headline => "a package to work with collections of cells, polyominoes and associated binomial ideals ", - EM "PolyominoIdeals", " is a package for making several computations with collections of cells, polyominoes and binomial ideals attached to them.\n ", +document { + Key => PolyominoIdeals, + Headline => "a package to work with collections of cells, polyominoes and associated binomial ideals ", + EM "PolyominoIdeals", " is a package for making several computations with collections of cells, polyominoes and binomial ideals attached to them.\n ", BR{},BR{}, "Collections of cells, and in particular polyominoes, are plane figures formed by joining unit squares edge to edge. The systematic study of polyominoes was initiated by Solomon W. Golomb in 1953 and further developed in his seminal monograph [G1994]. Beyond their combinatorial interest in problems such as tiling the plane, polyominoes also connect to several other fields, including theoretical computer science, statistical physics, and discrete geometry.\n", BR{},BR{}, @@ -952,13 +952,21 @@ BR{},BR{}, BR{}, "A collection $\\mathcal{P}$ is a polyomino if for every two cells $A,B\\in\\mathcal{P}$ there exists a sequence $A=C_1,\\dots,C_m=B$ of cells in $\\mathcal{P}$ such that $C_i$ and $C_{i+1}$ share a common edge for all $i$. In this case $I_{\\mathcal{P}}$ is called the polyomino ideal of $\\mathcal{P}$.\n", BR{},BR{}, - "The aim of this package is to provide several tools to help mathematicians in the study of collections of cells, polyominoes and the related binomial ideals. Every contribution is very welcome. \n", - BR{},BR{}, - BOLD "Literature \n", - UL { - LI {"[G1994] ", EM "Polyominoes, Puzzles, Patterns, Problems, and Packagings", "(S.W. Golomb, 1994, Second edition, Princeton University Press).\n"}, -LI {"[HH2012] ", EM "Ideals generated by adjacent 2-minors", "(J. Herzog, T. Hibi, 2012, J. Commut. Algebra).\n"}, - LI {"[AAQ2012] ", EM "Ideals generated by 2-minors, collections of cells and stack polyominoes ", "(A. A. Qureshi, 2012, J. Algebra).\n"} + "The aim of this package is to provide several tools to help mathematicians in the study of collections of cells, polyominoes and the related binomial ideals. Every contribution is very welcome. \n", + BR{},BR{}, + "A quick start is to build a small collection of cells, compute its polyomino ideal, and inspect its vertices.", + BR{}, BR{}, + EXAMPLE { + "Q = cellCollection {{1,1}, {2,1}, {2,2}}", + "I = polyoIdeal Q", + "polyoVertices Q" + }, + BR{},BR{}, + BOLD "Literature \n", + UL { + LI {"[G1994] ", EM "Polyominoes, Puzzles, Patterns, Problems, and Packagings", "(S.W. Golomb, 1994, Second edition, Princeton University Press).\n"}, + LI {"[HH2012] ", EM "Ideals generated by adjacent 2-minors", "(J. Herzog, T. Hibi, 2012, J. Commut. Algebra).\n"}, + LI {"[AAQ2012] ", EM "Ideals generated by 2-minors, collections of cells and stack polyominoes ", "(A. A. Qureshi, 2012, J. Algebra).\n"} }, Subnodes => { @@ -1005,12 +1013,18 @@ LI {"[HH2012] ", EM "Ideals generated by adjacent 2-minors", "(J. Herzog, T. Hib -------------------------------- Documentation for exported functions ------------------------------ ---------------------------------------------------------------------------------------------------- -document { - Key => {CollectionOfCells}, - Headline => "Type representing a collection of cells", - "Represents the type of a collection of cells, which is used as an input and output type - for several functions in this package." -} +document { + Key => {CollectionOfCells}, + Headline => "Type representing a collection of cells", + "Represents the type of a collection of cells, which is used as an input and output type + for several functions in this package.", + BR{}, BR{}, + EXAMPLE { + "Q = cellCollection {{1,1}, {2,1}, {2,2}}", + "Q" + }, + SeeAlso => {cellCollection, polyoIdeal, polyoVertices} +} document { @@ -2183,4 +2197,4 @@ assert( rankCollection Q == 4 ); /// -end \ No newline at end of file +end diff --git a/M2/Macaulay2/packages/QuillenSuslin.m2 b/M2/Macaulay2/packages/QuillenSuslin.m2 index a239164f1a6..dbeb71a66f4 100644 --- a/M2/Macaulay2/packages/QuillenSuslin.m2 +++ b/M2/Macaulay2/packages/QuillenSuslin.m2 @@ -1967,7 +1967,15 @@ document { {"A. Logar and B. Sturmfels.", EM " Algorithms for the Quillen-Suslin theorem.", " J. Algebra, 145(1):231-239, 1992."}, {"A. Fabianska and A. Quadrat." , EM " Applications of the Quillen-Suslin theorem to multidimensional systems theory.", " Grobner bases in control theory and signal processing.", " Radon Series Comp. Appl. Math (3):23-106, 2007."} }, - + PARA{}, "A first example computes a free basis for the kernel of a unimodular row.", + EXAMPLE { + "R = QQ[x,y]", + "f = matrix{{x^2*y+1,x+y-2,2*x*y}}", + "P = ker f", + "B = computeFreeBasis P", + "image B == P" + }, + SeeAlso => { "computeFreeBasis", "qsAlgorithm", "qsIsomorphism", CheckProjective, CheckUnimodular } } document { @@ -2508,11 +2516,26 @@ document { document { Key => {CheckProjective}, Headline => "optional input which gives the user the option to check whether the given module is projective", + EXAMPLE { + "R = QQ[x,y]", + "f = matrix{{x^2*y+1,x+y-2,2*x*y}}", + "P = ker f", + "phi = qsIsomorphism(P, CheckProjective => true)", + "isIsomorphism phi" + }, + SeeAlso => { "qsIsomorphism", "computeFreeBasis" } } document { Key => {CheckUnimodular}, Headline => "optional input which gives the user the option to check whether the given matrix is unimodular", + EXAMPLE { + "R = QQ[x,y]", + "f = matrix{{x^2*y+1,x+y-2,2*x*y}}", + "U = qsAlgorithm(f, CheckUnimodular => true)", + "f*U" + }, + SeeAlso => { "qsAlgorithm", "horrocks" } } diff --git a/M2/Macaulay2/packages/RandomComplexes.m2 b/M2/Macaulay2/packages/RandomComplexes.m2 index 35c9377d86f..7479b354bc9 100644 --- a/M2/Macaulay2/packages/RandomComplexes.m2 +++ b/M2/Macaulay2/packages/RandomComplexes.m2 @@ -241,9 +241,17 @@ doc /// syzygy matrices. The second method (@TO "randomSimplicialComplex"@) uses Stanley-Reisner rings from randomly chosen monomial ideals. + Example + h={1,4,6,5,1} + r={1,3,3,4} + C=randomChainComplex(h,r) + for i from 0 to 4 list rank HH_i C Caveat Some functionality here should be moved elsewhere, e.g. @TO "disturb"@, @TO "histogram"@, @TO "maximalEntry"@, and @TO "normalize"@. + SeeAlso + randomChainComplex + disturb /// @@ -498,6 +506,8 @@ doc /// Description Text If ZeroMean=>true then the integer of given Height values are randomly chosen with a zero mean + Example + randomChainComplex({20,20},{20},ZeroMean=>true) /// doc /// @@ -509,6 +519,8 @@ doc /// Text If WithLLL=>true then syzygy matrices of the randomly chosen matrices are improved for their Height by applying the LLL algorithm. + Example + randomChainComplex({1,1,1},{2,2},Height=>5,WithLLL=>true) /// doc /// @@ -521,6 +533,11 @@ doc /// Text If Strategy=>Continuous then we disturb the complex by floating point numbers otherwise by discrete values. + Example + C = randomChainComplex({1,1,1},{2,2}) + CR = C**RR_53 + disturb(CR,1e-4) + disturb(CR,1e-4,Strategy => Continuous) SeeAlso disturb /// diff --git a/M2/Macaulay2/packages/SymbolicPowers.m2 b/M2/Macaulay2/packages/SymbolicPowers.m2 index 23cdcd90d9d..c9728fdcf7b 100644 --- a/M2/Macaulay2/packages/SymbolicPowers.m2 +++ b/M2/Macaulay2/packages/SymbolicPowers.m2 @@ -619,13 +619,20 @@ document { " Invent. Math. 147 (2002), no. 2, 349–369."}, {"R. Villarreal.", EM " Monomial algebras.", " Second edition. Monographs and Research Notes in Mathematics. CRC Press, Boca Raton, FL, 2015. xviii+686 pp. ISBN: 978-1-4822-3469-5."}, - {"Hailong Dao, Alessandro De Stefani, Eloísa Grifo, Craig Huneke, and Luis Núñez-Betancourt. ", - EM "Symbolic powers of ideals.", "in Singularities and foliations. Geometry, topology and applications, pp. 387-432, Springer Proc. Math. Stat., 222, Springer, Cham, 2018. See ", HREF("https://arxiv.org/abs/1708.03010","https://arxiv.org/abs/1708.03010"), "."} - }, + {"Hailong Dao, Alessandro De Stefani, Eloísa Grifo, Craig Huneke, and Luis Núñez-Betancourt. ", + EM "Symbolic powers of ideals.", "in Singularities and foliations. Geometry, topology and applications, pp. 387-432, Springer Proc. Math. Stat., 222, Springer, Cham, 2018. See ", HREF("https://arxiv.org/abs/1708.03010","https://arxiv.org/abs/1708.03010"), "."} + }, + PARA{}, + "A first example asks for the smallest symbolic power contained in a fixed ordinary power.", + EXAMPLE lines /// + R = QQ[x,y,z]; + J = ideal(x*(y^3-z^3),y*(z^3-x^3),z*(x^3-y^3)); + containmentProblem(J,2) + ///, - SUBSECTION "Contributors", "The following people have generously - contributed code or worked on our code at various Macaulay2 - workshops.", + SUBSECTION "Contributors", "The following people have generously + contributed code or worked on our code at various Macaulay2 + workshops.", UL { "Ben Drabkin", @@ -1524,10 +1531,15 @@ doc /// SampleSize Headline optional parameter used for approximating asymptotic invariants that are defined as limits. + Example + R = QQ[x,y,z]; + J = ideal (x*(y^3-z^3),y*(z^3-x^3),z*(x^3-y^3)); + waldschmidt(J, SampleSize=>5) + asymptoticRegularity(J, SampleSize=>5) SeeAlso waldschmidt - lowerBoundResurgence - asymptoticRegularity + lowerBoundResurgence + asymptoticRegularity /// doc /// @@ -1575,6 +1587,10 @@ doc /// InSymbolic Headline an optional parameter used in containmentProblem. + Example + R = QQ[x,y,z]; + J = ideal (x*(y^3-z^3),y*(z^3-x^3),z*(x^3-y^3)); + containmentProblem(J,3,InSymbolic => true) SeeAlso containmentProblem diff --git a/M2/Macaulay2/packages/TSpreadIdeals.m2 b/M2/Macaulay2/packages/TSpreadIdeals.m2 index 109c5422a4d..13a9e8c4d24 100644 --- a/M2/Macaulay2/packages/TSpreadIdeals.m2 +++ b/M2/Macaulay2/packages/TSpreadIdeals.m2 @@ -673,14 +673,22 @@ beginDocumentation() ------------------------------------------------------- document { -Key => {TSpreadIdeals}, -Headline => "A package for working with t-spread ideals of polynomial rings", -"TSpreadIdeals is a package for creating and manipulating t-spread ideals of polynomial rings. Let ", TEX///$u=x_{i_1}x_{i_2}\cdots x_{i_d}$///, " a monomial of ", TEX///$S=K[x_1,\ldots,x_n]$///, ", with ", TEX///$1\le i_1\le i_2\le\dots\le i_d\le n$///, ". The monomial ", TT "u", " is called ", TEX///$t$///, "-spread if ", TEX///$i_{j+1}-i_j\ge t$///, " for all ", TEX///$j\in [d-1].$///, BR{}, -"A list of monomials is ", TT "t", "-spread if all the monomials of the list are ", TT "t", "-spread. A monomial ideal is called ", TT "t", "-spread if it is generated by ", TT "t", "-spread monomials.",BR{}, -"Some references can be found in the papers ", HREF("https://arxiv.org/abs/2110.11801","Computational methods for t-spread monomial ideals"), " and ", HREF("https://arxiv.org/abs/2105.11944","A numerical characterization of the extremal Betti numbers of t-spread strongly stable ideals"), ".", -Subnodes => { -"T-spread managing", - TO "tLastMon", +Key => {TSpreadIdeals}, +Headline => "A package for working with t-spread ideals of polynomial rings", +"TSpreadIdeals is a package for creating and manipulating t-spread ideals of polynomial rings. Let ", TEX///$u=x_{i_1}x_{i_2}\cdots x_{i_d}$///, " a monomial of ", TEX///$S=K[x_1,\ldots,x_n]$///, ", with ", TEX///$1\le i_1\le i_2\le\dots\le i_d\le n$///, ". The monomial ", TT "u", " is called ", TEX///$t$///, "-spread if ", TEX///$i_{j+1}-i_j\ge t$///, " for all ", TEX///$j\in [d-1].$///, BR{}, +"A list of monomials is ", TT "t", "-spread if all the monomials of the list are ", TT "t", "-spread. A monomial ideal is called ", TT "t", "-spread if it is generated by ", TT "t", "-spread monomials.",BR{}, +"Some references can be found in the papers ", HREF("https://arxiv.org/abs/2110.11801","Computational methods for t-spread monomial ideals"), " and ", HREF("https://arxiv.org/abs/2105.11944","A numerical characterization of the extremal Betti numbers of t-spread strongly stable ideals"), ".", +PARA {"Examples:"}, +EXAMPLE lines /// + S=QQ[x_1..x_16] + u=x_2*x_6*x_10*x_13 + tNextMon(u,3) + tLastMon(u,1,3) + tMacaulayExpansion(50,12,2,1,Shift=>true) +///, +Subnodes => { +"T-spread managing", + TO "tLastMon", TO "tPascalIdeal", TO "tSpreadList", TO "tSpreadIdeal", @@ -1363,34 +1371,50 @@ EXAMPLE lines /// -- Shift (for tMacaulayExpansion) ---------------------------------- -document { -Key => {Shift,[tMacaulayExpansion,Shift]}, -Headline => "optional boolean argument for tMacaulayExpansion", -"whether it is true the function tMacaulayExpansion gives the ", TEX///$i$///, "-th shifted Macaulay expansion of ", TEX///$a$///, ". Given four positive integers ", TEX///$(a,n,d,t)$///, " the ", TEX///$d$///,"-th shifted t-Macaulay expansion is a sum of binomials: ", TEX///$\binom{a_d}{d+1} + \binom{a_{d-1}}{d} + \cdots + \binom{a_j}{j+1}.$///, -SeeAlso =>{tMacaulayExpansion} -} +document { +Key => {Shift,[tMacaulayExpansion,Shift]}, +Headline => "optional boolean argument for tMacaulayExpansion", +"whether it is true the function tMacaulayExpansion gives the ", TEX///$i$///, "-th shifted Macaulay expansion of ", TEX///$a$///, ". Given four positive integers ", TEX///$(a,n,d,t)$///, " the ", TEX///$d$///,"-th shifted t-Macaulay expansion is a sum of binomials: ", TEX///$\binom{a_d}{d+1} + \binom{a_{d-1}}{d} + \cdots + \binom{a_j}{j+1}.$///, +PARA {"Examples:"}, +EXAMPLE lines /// + tMacaulayExpansion(50,12,2,1,Shift=>true) +///, +SeeAlso =>{tMacaulayExpansion} +} ---------------------------------- -- FixedMax (for tNextMon and countTLexMon) ---------------------------------- -document { -Key => {FixedMax,[tNextMon,FixedMax],[countTLexMon,FixedMax]}, -Headline => "optional boolean argument for tNextMon", -"whether it is ", TT "true", " the function ", TT "tNextMon(u,t,FixedMax=>true)", " gives the ", TT "t" , "-lex successor for which the maximum of the support is ", TEX///$\max\textrm{supp}(\texttt{u})$///, ". Given a ", TEX///$t$///, "-spread monomial ", TEX///$u=x_{i_1}x_{i_2}\cdots x_{i_d}$///,", we define ", TEX///$\textrm{supp}(u)=\{i_1,i_2,\ldots, i_d\}$///, ".", -SeeAlso =>{tNextMon, countTLexMon} -} +document { +Key => {FixedMax,[tNextMon,FixedMax],[countTLexMon,FixedMax]}, +Headline => "optional boolean argument for tNextMon", +"whether it is ", TT "true", " the function ", TT "tNextMon(u,t,FixedMax=>true)", " gives the ", TT "t" , "-lex successor for which the maximum of the support is ", TEX///$\max\textrm{supp}(\texttt{u})$///, ". Given a ", TEX///$t$///, "-spread monomial ", TEX///$u=x_{i_1}x_{i_2}\cdots x_{i_d}$///,", we define ", TEX///$\textrm{supp}(u)=\{i_1,i_2,\ldots, i_d\}$///, ".", +PARA {"Examples:"}, +EXAMPLE lines /// + S=QQ[x_1..x_16] + u=x_2*x_6*x_10*x_13 + tNextMon(u,3,FixedMax=>true) +///, +SeeAlso =>{tNextMon, countTLexMon} +} ---------------------------------- -- MaxInd (for tLastMon and countTLexMon) ---------------------------------- -document { -Key => {MaxInd,[tLastMon,MaxInd]}, -Headline => "optional integer argument for tLastMon", -"whether it is greater than -1 the function ", TT "tLastMon(u,t,MaxInd=>m)", " gives the smallest ", TT "t", "-spread monomial for which the maximum of the support is ", TEX///$\max\textrm{supp}(\texttt{u})$///, " of the Borel shadow of ", TEX///$B_\texttt{t}\{\texttt{u}\}$///, ". Given a ", TEX///$t$///, "-spread monomial ", TEX///$u=x_{i_1}x_{i_2}\cdots x_{i_d}$///,", we define ", TEX///$\textrm{supp}(u)=\{i_1,i_2,\ldots, i_d\}$///, ".", -SeeAlso =>{tLastMon, tShadow} -} +document { +Key => {MaxInd,[tLastMon,MaxInd]}, +Headline => "optional integer argument for tLastMon", +"whether it is greater than -1 the function ", TT "tLastMon(u,t,MaxInd=>m)", " gives the smallest ", TT "t", "-spread monomial for which the maximum of the support is ", TEX///$\max\textrm{supp}(\texttt{u})$///, " of the Borel shadow of ", TEX///$B_\texttt{t}\{\texttt{u}\}$///, ". Given a ", TEX///$t$///, "-spread monomial ", TEX///$u=x_{i_1}x_{i_2}\cdots x_{i_d}$///,", we define ", TEX///$\textrm{supp}(u)=\{i_1,i_2,\ldots, i_d\}$///, ".", +PARA {"Examples:"}, +EXAMPLE lines /// + S=QQ[x_1..x_16] + u=x_2*x_6*x_10*x_13 + tLastMon(u,1,3,MaxInd=>14) +///, +SeeAlso =>{tLastMon, tShadow} +} ------------------------------------------------------------ -- TESTS diff --git a/M2/Macaulay2/packages/TerraciniLoci.m2 b/M2/Macaulay2/packages/TerraciniLoci.m2 index 0157ade8d21..a3416a353df 100644 --- a/M2/Macaulay2/packages/TerraciniLoci.m2 +++ b/M2/Macaulay2/packages/TerraciniLoci.m2 @@ -142,6 +142,13 @@ doc /// This package exports one method, @TO terraciniLocus@, for computing the ideals of these varieties. + Example + R = QQ[s,t] + S = QQ[x_0..x_3] + f = map(R, S, {s^3, s^2*t, s*t^2, t^3}) + terraciniLocus(2, f) + SeeAlso + terraciniLocus Citation @article {MR5026390, AUTHOR = {Galuppi, Francesco and Santarsiero, Pierpaola and Torrance, From 3c4c2ebde2ae4c51bffb2855a74140350421c1ec Mon Sep 17 00:00:00 2001 From: klee669 Date: Mon, 18 May 2026 11:51:11 -0400 Subject: [PATCH 54/73] Completed NAG tutorial Replace the inline "Tutorial: Numerical algebraic geometry" content with a standalone tu_NAG.m2 using the doc /// Node format and update loads.m2 to load that file. The new tu_NAG.m2 restructures the tutorial into formal documentation nodes, cleans up examples, and adds sections on Monodromy methods, Numerical certification, and Numerical implicitization with corresponding examples and package references. --- M2/Macaulay2/packages/Macaulay2Doc/loads.m2 | 5 +- M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 | 301 +++++++++++++------ 2 files changed, 216 insertions(+), 90 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 b/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 index 9cb8d76171a..5157cf1acd3 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 @@ -94,7 +94,4 @@ document { Key => "Tutorial: Fano varieties", ld "tu_Fano.m2" } -document { - Key => "Tutorial: Numerical algebraic geometry", - ld "tu_NAG.m2" - } +load "./tu_NAG.m2" diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 b/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 index edb843c7e60..1334f8dd65a 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 @@ -1,86 +1,215 @@ --- {\it Numerical algebraic geometry} uses techniques from numerical analysis --- to study and approximate solutions of systems of polynomial equations. --- --- Traditionally, polynomial systems are studied using symbolic methods --- such as Gr\"obner bases, resultants, and elimination techniques. --- While these methods are powerful, they often become prohibitively slow --- for large or complicated systems. --- Numerical algebraic geometry provides an alternative by replacing exact symbolic computations --- with high-precision numerical approximations. - - - ------------------------------------------------ --- A. Homotopy continuation ------------------------------------------------ --- The central tool in numerical algebraic geometry is {\it homotopy continuation}. --- This method constructs a homotopy between two polynomial systems --- and tracks solutions from one system to the other. --- --- Typically, one system is chosen so that its solutions are already known --- or easy to compute; the {\it start system}. --- The other system is the polynomial system of interest, called the {\it target system}. --- --- One common constructions is the {\it straight-line homotopy}. --- Given a target system $f$ and a start system $g$, the homotopy is defined by --- $H(x,t) = (1-t)g(x) + tf(x)$. --- Starting from a known solution $x^*$ of $g$ at $t=0$, --- it tracks the solution path as $t$ moves toward $1$, --- approximating a solution of $f$. --- --- The package {\tt NumericalAlgebraicGeometry} provides fundamental tools --- in numerical algebraic geometry. - ---^ -needsPackage "NumericalAlgebraicGeometry" ---$ - -R = CC[x,y] -g = {x^2-1,y^2-1} -f = {x^2+y^2-1, (x-y)^2-1} -solsS = {(1,-1),(1,1),(-1,1),(-1,-1)} -track(g,f,solsS) - --- In this example, the start system is a {\it B\'ezout start system}. --- giving a total number of paths equal to the product of the degrees --- of the defining polynomials. This number is an upper bound --- for the number of isolated solutions of the target system. - --- The same computation can also be simply carried out using: ---^ -R = CC[x,y]; ---$ - -f = {x^2+y^2-1, (x-y)^2-1}; -solveSystem f - - ------------------------------------------------ --- B. Witness sets and numerical irreducible decomposition ------------------------------------------------ --- The idea of homotopy continuation for finding a solution to zero-dimensional systems --- extends to the study positive-dimensional varieties. --- The key observation is that intersecting a positive-dimensional variety --- with codimension-many generic linear slices produces a zero-dimensional variety. --- --- The data consisting of a polynomial system, a collection of generic linear slices, --- and the resulting finite set of points is called a {\it witness set}. --- Witness sets provide a numerical representation of --- positive-dimensional algebraic varieties and can be used to compute: --- --- 1. dimension --- --- 2. degree --- --- 3. sampling from a variety --- --- 4. irreducible decomposition of a variety --- --- This computation can be carried out using: ---^ -R = CC[x,y,z]; ---$ - -I = ideal {(x^2+y^2+z^2-1)*(y-x^2), (x^2+y^2+z^2-1)*(z-x^3)}; -W = components numericalIrreducibleDecomposition I -- the variety consists of two components -sample first W -- sampling a random point on the first component +doc /// +Node + Key + "Tutorial: Numerical algebraic geometry" + Headline + Numerical algebraic geometry + Description + Text + {\it Numerical algebraic geometry} uses techniques from numerical analysis + to study and approximate solutions of systems of polynomial equations. + + Traditionally, polynomial systems are studied using symbolic methods + such as Gr\"obner bases, resultants, and elimination techniques. + While these methods are powerful, they often become prohibitively slow + for large or complicated systems. + Numerical algebraic geometry provides an alternative by replacing exact + symbolic computations with high-precision numerical approximations. + + Text + @BOLD "A. Homotopy continuation"@ + + Text + The central tool in numerical algebraic geometry is {\it homotopy continuation}. + This method constructs a homotopy between two polynomial systems + and tracks solutions from one system to the other. + + Typically, one system is chosen so that its solutions are already known + or easy to compute; this is called the {\it start system}. + The other system is the polynomial system of interest, called the + {\it target system}. + + One common construction is the {\it straight-line homotopy}. + Given a target system $f$ and a start system $g$, the homotopy is + defined by + $H(x,t) = (1-t)g(x) + tf(x)$. + Starting from a known solution $x^*$ of $g$ at $t=0$, one tracks the + solution path as $t$ moves toward $1$, approximating a solution of $f$. + + The package @TO "NumericalAlgebraicGeometry"@ provides fundamental tools + in numerical algebraic geometry. + + Example + needsPackage "NumericalAlgebraicGeometry" + R = CC[x,y] + g = {x^2-1,y^2-1} + f = {x^2+y^2-1, (x-y)^2-1} + solsS = {(1,-1),(1,1),(-1,1),(-1,-1)} + track(g,f,solsS) + + Text + In this example, the start system is a {\it B\'ezout start system}, + giving a total number of paths equal to the product of the degrees + of the defining polynomials. This number is an upper bound + for the number of isolated solutions of the target system. + + The same computation can also be carried out using: + + Example + R = CC[x,y]; + f = {x^2+y^2-1, (x-y)^2-1}; + solveSystem f + + Text + @BOLD "B. Witness sets and numerical irreducible decomposition"@ + + Text + The idea of homotopy continuation for finding solutions to + zero-dimensional systems extends to the study of positive-dimensional + varieties. The key observation is that intersecting a positive-dimensional + variety with sufficiently many generic linear slices produces a + zero-dimensional variety. + + The data consisting of a polynomial system, a collection of generic + linear slices, and the resulting finite set of points is called a + {\it witness set}. Witness sets provide a numerical representation of + positive-dimensional algebraic varieties and can be used to compute: + + @UL { + LI "dimension", + LI "degree", + LI "sampling from a variety", + LI "irreducible decomposition of a variety" + }@ + + Example + R = CC[x,y,z]; + I = ideal { + (x^2+y^2+z^2-1)*(y-x^2), + (x^2+y^2+z^2-1)*(z-x^3) + }; + W = components numericalIrreducibleDecomposition I + sample first W + + Text + @BOLD "C. Monodromy methods"@ + + Text + When homotopy continuation is used to compute all solutions + of a polynomial system, one typically chooses a start system + whose number of solutions gives an upper bound + for the number of isolated solutions of the target system. + In practice, however, finding a good upper bound may be difficult. + + {\it Monodromy methods} provide a heuristic alternative. + For a polynomial system depending on parameters, as the parameters vary + continuously, the solutions trace paths. Following these paths along + loops in parameter space may transform one solution into another; + this is the {\it monodromy action}. + + The resulting monodromy action on the solution set is transitive when + the solution variety is irreducible. Consequently, starting from a subset + of known solutions, monodromy loops can be used to find all remaining + solutions. + + The package @TO "MonodromySolver"@ implements these techniques + for solving polynomial systems numerically. + + Example + needsPackage "MonodromySolver" + setRandomSeed 0; + declareVariable \ {A,B,C,D,X,Y}; + F = gateSystem( + matrix{{A,B,C,D}}, + matrix{{X,Y}}, + matrix{{A*(X-1)^2-B}, {C*(Y+2)^2+D}} + ); -- Define a parameter system with parameters A,B,C,D in variables X,Y + p0 = point{{1,1,1,1}}; + sols = solveFamily(p0, F, NumberOfNodes=>3) + + Text + One can also compute the permutations induced by the monodromy action. + + Example + monodromyGroup(F,"msOptions" => {NumberOfEdges=>10}) + + Text + @BOLD "D. Numerical certification"@ + + Text + Numerical homotopy continuation computes approximations to solutions + of polynomial systems. An important question is whether these + approximations correspond to actual solutions, and whether they can be + refined to high precision. + + The package @TO "NumericalCertification"@ provides rigorous guarantees + for numerical computations in algebraic geometry. These methods are based + on Smale's alpha-theory and Krawczyk's method, which give criteria + ensuring that a numerical approximation lies in a neighborhood of an + exact solution. + + Certification can be used to verify: + + @UL { + LI "existence of a nearby exact solution", + LI "distinctness of computed solutions", + LI "reality of solutions" + }@ + + Example + needsPackage "NumericalCertification" + R = CC[x1,x2,y1,y2]; + F = polySystem { + 3*y1 + 2*y2 -1, + 3*x1 + 2*x2 -3.5, + x1^2 + y1^2 -1, + x2^2 + y2^2 -1 + }; + sols = solveSystem F; + c = certifySolutions(F, sols); + peek c + + Text + @BOLD "E. Numerical implicitization"@ + + Text + The numerical methods introduced so far assume that a variety is given + by its defining polynomial equations. In many applications, however, + varieties arise instead as images of polynomial maps, given by + parametrizations. + + {\it Implicitization} is the process of recovering intrinsic equations + defining the image from its parametrization. + + In many situations, one is interested not necessarily in the full + defining equations, but rather in basic geometric information about the + image variety. Examples include: + + @UL { + LI "dimension", + LI "degree", + LI "Hilbert function values", + LI "membership tests for points" + }@ + + The package @TO "NumericalImplicitization"@ provides numerical methods + for extracting such information directly from a parametrization, + avoiding costly symbolic computations whenever possible. + + The package builds on existing numerical algebraic geometry software, + including @TO "NumericalAlgebraicGeometry"@ and @TO "MonodromySolver"@. + + Example + needsPackage "NumericalImplicitization" + R = CC[m_(1,1)..m_(2,4)]; + I = ideal 0_R; + F = (minors(2, genericMatrix(R, 2, 4)))_*; + numericalImageDim(F, I) + numericalImageDegree(F, I, Verbose => false) + q = first numericalImageSample(F, I) -- sampling a point from the variety + isOnImage(F, I, q, Verbose => false) + + + Text + This tutorial is written by Kisun Lee. +/// From e697085835ebe2b2ead8f6aafcdb420d3a85ad54 Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Tue, 19 May 2026 10:49:00 -0400 Subject: [PATCH 55/73] add caveats --- M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 index 10380a88bce..4f07cc69702 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 @@ -107,6 +107,8 @@ Description @TT "SubringLimit => n"@ -- an option for @TO kernel@ which causes the computation of the kernel of a ring map to stop after @TT "n"@ elements have been discovered. +Caveat + Used only for computing the kernel of a @TO RingMap@. /// @@ -120,6 +122,8 @@ Description @TT "DegreeLimit => d"@ -- an option for @TO kernel@ which causes the computation of the kernel of a ring map to stop after generators for the degree @TT "d"@ part of the kernel have been discovered. +Caveat + Used only for computing the kernel of a @TO RingMap@. /// @@ -131,6 +135,8 @@ Headline Description Text This option is passed through to @TO gb@ when computing the kernel of a @TT "RingMap"@. +Caveat + Used only for computing the kernel of a @TO RingMap@. SeeAlso gb /// From adca88064b91dc368d7905ac38bae9259a09af9d Mon Sep 17 00:00:00 2001 From: aalmousa Date: Tue, 19 May 2026 16:54:57 -0400 Subject: [PATCH 56/73] docs: refresh repo entrypoints and workflow guidance --- .github/pull_request_template.md | 8 +- DocumentationGuide.md | 241 -------- DocumentationPlan.md | 517 ------------------ M2/BUILD/README.md | 9 +- M2/Macaulay2/editors/README.md | 29 +- M2/Macaulay2/editors/prism/README.md | 9 +- M2/Macaulay2/editors/pygments/README.md | 12 +- M2/Macaulay2/editors/vim/README_linux | 13 +- M2/Macaulay2/editors/vim/README_macos | 8 +- M2/Macaulay2/packages/BeginningMacaulay2.m2 | 2 +- .../packages/BeginningMacaulay2/tutorial | 7 +- M2/Macaulay2/packages/README | 30 +- M2/README.md | 6 +- README.md | 24 +- 14 files changed, 85 insertions(+), 830 deletions(-) delete mode 100644 DocumentationGuide.md delete mode 100644 DocumentationPlan.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 55d6fb32eb1..05ae381ce8c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -4,7 +4,7 @@ Describe the documentation change and the main files it touches. ## Related Issue -Link the issue in `aalmousa/M2` that this PR addresses. +Link the issue in `Macaulay2/M2` or `aalmousa/M2` that this PR addresses. ## Verification @@ -13,8 +13,6 @@ html, or any verification you could not complete. ## Notes -- For the documentation refresh workflow in this fork, open PRs against - `doc-updates`, not `master`. - Keep the scope focused. Split unrelated documentation work into separate PRs. -- See `DocumentationGuide.md` and `DocumentationStyleGuide.md` for the current - workflow and documentation standards. +- See `README.md` and the Macaulay2 wiki for the current contribution + workflow. diff --git a/DocumentationGuide.md b/DocumentationGuide.md deleted file mode 100644 index cd7127f29a0..00000000000 --- a/DocumentationGuide.md +++ /dev/null @@ -1,241 +0,0 @@ -# Documentation Guide - -This guide is for contributors working on the documentation refresh in -`aalmousa/M2`. Use it together with [DocumentationPlan.md](DocumentationPlan.md). - -The repo-local guides are aligned with these upstream documentation references: - -- -- - -Use the upstream pages for the full package-writing and documentation syntax -details. Use this guide for the branch workflow, local preview, and review -expectations for the documentation refresh, along with the repo-local -documentation standards that reviewers should enforce. - -## Scope - -The main documentation surfaces in this repository are: - -- Core and user-facing docs: `M2/Macaulay2/packages/Macaulay2Doc/` -- Package docs: `M2/Macaulay2/packages//` and package `.m2` files -- Internal docs: `M2/Macaulay2/docs/` -- Repo-level docs: `README.md`, `M2/BUILD/`, `M2/Macaulay2/editors/`, and - related README files - -Edit source documentation, not generated html. - -Macaulay2 documentation is written in one of two supported forms: - -- `document(List)` using the list-based hypertext format -- `doc(String)` using the string-based `SimpleDoc` format - -Documentation entries belong to a package and should occur after that package's -`beginDocumentation()` section. - -## What Good Documentation Must Do - -- Help a mathematically literate user do the next thing quickly. -- Make the next useful page, package, or example easy to find. -- Stay accurate for the current code. -- Keep examples small, clear, and trustworthy. - -## Workflow - -1. Claim or create an issue in `aalmousa/M2` and track it in the - `M2 Documentation Refresh` project. -2. Branch from `doc-updates`. -3. Keep the PR focused on one issue or one child issue. -4. Open pull requests against `aalmousa/M2:doc-updates`, not `master`. -5. If the scope grows, split follow-up work into new issues instead of widening - the PR. - -## Documentation Standards - -### Required Standards - -- Do not leave `TODO`, `FIXME`, `Section XX`, or references to missing - follow-up tutorials in user-facing pages. -- Avoid stale course framing, old version-era notes, and obsolete performance - caveats unless they still matter. -- If a symbol is exported, it should normally be documented rather than left - `undocumented`. -- Every new page should be reachable from at least one parent page. -- Preview the rendered page when practical, and check links and - cross-references before merge. - -### Function And Method Pages - -When the documentation surface supports it, include: - -- `Headline` -- `Usage` -- `Inputs` -- `Outputs` -- a short explanation of behavior -- at least one example or a strong cross-reference -- `SeeAlso` - -Use these conventions: - -- Keep titles and headlines lowercase unless a proper noun requires capitals. -- Make the `Headline` a short phrase, not a full sentence. -- Use `TO` for links to functions, options, variables, packages, and doc - nodes. -- Do not end `Inputs`, `Outputs`, or `Consequences` entries with periods. -- In `Outputs`, say both the type and what mathematical object or value is - returned. -- For method functions, document the return type when possible. -- If an option materially changes behavior, document the option node too. -- Prefer the page shapes already used in `PackageTemplate.m2`, `Macaulay2Doc`, - and `SimpleDoc`. - -### Package Landing Pages - -A package landing page should answer these questions quickly: - -- What does the package do? -- What package needs to be loaded? -- Are there external prerequisites? -- Where should a new user start? -- Where are the main examples or tutorials? - -### Tutorials - -- State the goal near the top. -- Say what packages need to be loaded. -- Present examples in an order a reader can follow. -- Keep explanatory text separate from raw test material. -- If external software or setup is required, say so early. - -### Internal Or Generated Docs - -- Say whether the page is hand-maintained or generated. -- Point readers to the right source file or build context. -- Do not present an internal page as a user-facing landing page. - -### Writing Rules - -- Write for the page's audience, not for someone already reading the source. -- Prefer direct present-tense statements. -- Explain package-specific or Macaulay2-specific terms when they are not - obvious. -- Use Macaulay2 identifiers as code references, not as English words in prose. -- Start sentences with English words, not identifiers or symbols. -- Use lowercase common nouns like `list` or `hash table` unless you mean the - class `List` or `HashTable`. -- Write real sentences with normal punctuation. -- Use Unicode where appropriate. -- Keep contributor lists off user landing pages unless they are actively - maintained and clearly belong there. - -### Examples - -- Each documented exported data type, method, and function should normally have - at least one example. -- Prefer one minimal example and one slightly richer example over a long dump. -- Choose examples that show real usage without consuming excessive CPU time or - memory. -- If output is expensive, unstable, or externally dependent, say so explicitly. -- Do not place large example blocks back-to-back without explanation. -- Do not reload the package being documented inside examples. -- In `Usage` and `Outputs`, avoid assigning a single returned value to a - variable unless that assignment is needed to explain a later step. - -## Before Editing - -- Identify the audience first: end user, package user, contributor, or internal - maintainer. -- Find the source page that actually generates the docs you want to change. -- Prefer improving an existing landing page or tutorial path over creating a - second entry point for the same material. -- Check whether the issue should carry `needs-math-review` or `needs-example`. - -## Local Preview - -Assume `$M2BUILDDIR` points to an existing build tree. For most documentation -changes, rebuild only the package you touched. - -For prose, navigation, or landing-page edits that do not change example code: - -```sh -make -C "$M2BUILDDIR/Macaulay2/packages" \ - PACKAGES=Macaulay2Doc \ - RemakePackages=false \ - RemakeAllDocumentation=false \ - CheckDocumentation=false \ - IARGS='RunExamples => false' -``` - -Replace `Macaulay2Doc` with the package you edited. The regenerated html usually -appears under: - -```text -$M2BUILDDIR/usr-dist/common/share/doc/Macaulay2//html/ -``` - -If you changed examples or expected output, use the normal package rebuild: - -```sh -make -C "$M2BUILDDIR/Macaulay2/packages" \ - PACKAGES=YourPackage \ - RemakePackages=false \ - RemakeAllDocumentation=false -``` - -For package docs, also use `viewHelp` or `installPackage` when that is the -quickest way to confirm the rendered result. - -For a normal documentation-writing cycle, the built-in documentation recommends: - -1. edit the documentation source -2. run `installPackage("YourPackage")` -3. review the result with `viewHelp` - -Reserve the expensive flags for final verification: - -- `RunExamples => false`: fastest preview for text-only edits -- default example behavior: normal path for example changes -- `RerunExamples=true`: rerun all examples for one package -- `RemakeAllDocumentation=true`: full package-doc rebuild -- `CheckDocumentation=true`: stronger completeness check - -If there is a pre-existing build failure, say exactly what page or command you -were still able to verify. - -## Verification - -Every documentation PR should say what was checked locally. Use this checklist: - -- the affected page renders or `viewHelp` shows the expected change -- links, `SeeAlso`, `Subnodes`, and top-level navigation were checked -- examples were rerun when practical, or the PR says why they were not -- any external prerequisite or setup instructions were checked against current - reality - -Before merge, also confirm: - -- the PR says what was verified and what was not -- the change matches the current audience and page type -- any unresolved uncertainty about examples or outputs is stated plainly - -## Labels And Review - -Use the repo labels to keep work triageable: - -- `documentation`: default label for documentation work -- `docs-build`, `docs-reference`, `docs-package`, `docs-tutorial`, - `docs-editors`: documentation area labels -- `needs-math-review`: use when correctness depends on mathematical review -- `needs-example`: use when examples or outputs should be rerun -- `blocked`: use when another issue must land first - -## Definition Of Done - -A documentation change is ready when: - -1. The audience and affected files are clear. -2. The text is accurate for the current code or workflow. -3. Links and cross-references were checked. -4. Examples were rerun when practical, or the limitation is stated plainly. -5. The PR explains verification and links the relevant issue. diff --git a/DocumentationPlan.md b/DocumentationPlan.md deleted file mode 100644 index 1bf3458ec4e..00000000000 --- a/DocumentationPlan.md +++ /dev/null @@ -1,517 +0,0 @@ -# Documentation Plan - -This file coordinates the documentation refresh work currently landing on -`doc-updates`. - -Use GitHub issues and a GitHub Project to track execution. Do not treat this -file as the day-to-day checklist for every edit. Its job is to define scope, -workflow, and the first backlog to turn into issues. - -## Goals - -1. Improve the accuracy of user-facing documentation. -2. Make documentation work easier to claim, review, and finish. -3. Standardize how documentation tasks are described and verified. -4. Keep pull requests small enough for mathematical and editorial review. - -## Working Model - -1. Create a GitHub Project named `M2 Documentation Refresh`. -2. Use columns `Backlog`, `Ready`, `In Progress`, `In Review`, and `Done`. -3. File one GitHub issue per documentation task. -4. Link each issue to the relevant paths, a clear owner, and a definition of - done. -5. Land focused pull requests into `doc-updates`, not one large omnibus PR. -6. Close the issue only after review and any needed follow-up verification. - -Contributor-facing guidance lives in -[DocumentationGuide.md](DocumentationGuide.md). - -## Suggested Labels - -- `documentation`: default label for documentation work. -- `docs-build`: install, build, packaging, or toolchain documentation. -- `docs-reference`: reference pages, generated docs, or API-style docs. -- `docs-package`: package-specific documentation. -- `docs-tutorial`: tutorials, examples, and teaching-oriented docs. -- `docs-editors`: editor integration and syntax-highlighting docs. -- `needs-math-review`: requires subject-matter review for correctness. -- `needs-example`: examples must be rerun or rewritten. -- `good first issue`: suitable for a new contributor. -- `blocked`: cannot proceed until another issue lands. - -## Definition Of Done - -A documentation issue is done when all of the following are true: - -1. The affected files and audience are identified in the issue. -2. The updated text is accurate for the current code or workflow. -3. Examples, commands, or screenshots were rerun when practical, or the PR - explicitly notes what could not be rerun. -4. Links and cross-references in the touched files were checked. -5. The PR description states how the change was verified. -6. The issue is linked to the PR and any follow-up work is split into new - issues instead of hidden in review comments. - -## Issue Size Guidance - -- Small: one file or one tightly scoped topic; target one review. -- Medium: one subsystem or one package doc surface; may span several files. -- Large: an audit or rewrite that should be split into smaller child issues. - -Default to small or medium issues. Large issues should usually be tracking -issues, not implementation issues. - -## Review Checklist - -When reviewing documentation PRs, check: - -1. Is the text correct for the current version of the code? -2. Is the intended audience clear? -3. Do the examples still run, or is any uncertainty called out? -4. Are links, package names, branch names, and paths still current? -5. Is the PR small enough to review without hidden scope? - -## Starter Backlog - -The items below are intended to become GitHub issues. Each one is small enough -to assign to a person or pair, and together they cover the main documentation -surfaces already present in this repository. - -### Coordination And Contributor Guidance - -1. Audit top-level contribution guidance. - Paths: `README.md`, `.github/pull_request_template.md` - Done when: contributor-facing instructions are current, critical workflow - notes live in the repo when possible, and stale references are removed or - flagged. - -2. Add a short documentation contributor guide. - Paths: `DocumentationPlan.md`, new guide if needed - Done when: contributors can tell where package docs, internal docs, and - README-style docs live, and how to claim work. - -3. Define documentation style conventions. - Paths: new guide or repo-local section linked from `DocumentationPlan.md` - Done when: reviewers have a shared standard for headings, code blocks, link - style, example formatting, and tone. - -4. Establish the documentation project board and label set on GitHub. - Paths: GitHub Project and repo labels - Done when: the board exists, labels are created, and at least the initial - backlog issues are loaded. - -### Build, Install, And Tooling Docs - -5. Audit the main build overview. - Paths: `M2/README.md`, `M2/BUILD/README.md` - Done when: supported workflows, prerequisite expectations, and entry points - are clear and non-duplicative. - -6. Review container and packaging documentation. - Paths: `M2/BUILD/docker/README.md`, `M2/BUILD/docker/*/README.md`, - `M2/BUILD/rpm/README.md` - Done when: the supported images and packaging flows are accurately described - and obsolete instructions are called out. - -7. Review editor integration documentation. - Paths: `M2/Macaulay2/editors/README.md`, - `M2/Macaulay2/editors/emacs/README.md`, - `M2/Macaulay2/editors/vim/README_linux`, - `M2/Macaulay2/editors/vim/README_macos`, - `M2/Macaulay2/editors/prism/README.md`, - `M2/Macaulay2/editors/pygments/README.md` - Done when: installation and usage instructions match the current editor - tooling and redundant text is reduced. - -8. Document how to verify documentation changes locally. - Paths: repo-local guide or existing README files - Done when: contributors know what to run for doc-adjacent checks and how to - report partial verification. - -### Internal And Generated Documentation - -9. Audit the internal documentation landing page. - Paths: `M2/Macaulay2/docs/index.rst`, `M2/Macaulay2/docs/modules.rst` - Done when: the landing page accurately describes what is generated, what is - hand-maintained, and where readers should start. - -10. Review Sphinx and Doxygen build assumptions. - Paths: `M2/Macaulay2/docs/CMakeLists.txt`, `M2/Macaulay2/docs/conf.py`, - `M2/Macaulay2/docs/Doxyfile.in` - Done when: build expectations are documented and mismatches between config - and prose are recorded or fixed. - -11. Inventory major gaps in internal docs coverage. - Paths: `M2/Macaulay2/docs/`, generated output as needed - Done when: missing modules, weak landing pages, and unclear navigation are - captured as follow-up issues instead of remaining implicit. - -### Package Documentation - -12. Audit the package documentation entry point. - Paths: `M2/Macaulay2/packages/README` - Done when: readers can understand how package docs are organized and how to - discover package-specific documentation. - -13. Redesign the main Macaulay2 documentation landing page. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2` - Done when: the landing page is organized for mathematicians and other - users trying to find examples, tutorials, package docs, and topic-based - entry points, and the rendered html has been previewed locally. - -14. Surface buried high-value guides from the main documentation landing page. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/ov_language.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/ov_packages.m2`, - `M2/Macaulay2/packages/BeginningMacaulay2.m2` - Done when: the homepage or nearby top-level navigation makes it easier to - find `BeginningMacaulay2`, `debugging`, `the debugger`, `error handling`, - and practical package-usage guidance, and any new links have been checked - in rendered html. - -15. Remove or relocate the stale contributor list on the main documentation landing page. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2`, - related author or acknowledgement pages as needed - Done when: the hand-maintained documentation-contributor list no longer - clutters the homepage, and any remaining attribution is either accurate and - maintainable or moved to a more appropriate page. - -16. Review `NumericalAlgebraicGeometry` documentation. - Paths: `M2/Macaulay2/packages/NumericalAlgebraicGeometry/README`, - `M2/Macaulay2/packages/NumericalAlgebraicGeometry/TST/README.txt` - Done when: overview, prerequisites, and example/test references are current. - -17. Review `NumericalSchubertCalculus` documentation. - Paths: `M2/Macaulay2/packages/NumericalSchubertCalculus/README` and related - README files under that package - Done when: the overview and supporting README files still reflect the - current package layout and usage. - -18. Review `OldChainComplexes` documentation structure. - Paths: `M2/Macaulay2/packages/OldChainComplexes/docs/*.m2` - Done when: the landing points, narrative flow, and page naming are coherent - for a newcomer to the package docs. - -19. Review `MergeTeX` documentation. - Paths: `M2/Macaulay2/packages/MergeTeX/README.md` - Done when: setup and usage notes are accurate and concise. - -20. Review `TropicalToric` documentation. - Paths: `M2/Macaulay2/packages/TropicalToric/README.md` - Done when: the README accurately describes scope, entry points, and any - external assumptions. - -21. Review `MonodromySolver` example documentation. - Paths: `M2/Macaulay2/packages/MonodromySolver/paper-examples/README.md` - Done when: the example documentation clearly states what is reproducible and - what environment assumptions exist. - -22. Identify packages missing an overview or landing page. - Paths: `M2/Macaulay2/packages/` - Done when: missing-package-doc issues are filed as discrete follow-ups - instead of one vague umbrella task. - -Audit summary from the first static distributed-package scan on `2026-04-25`: -the 294 distributed packages showed no broken relative links in their -README/Markdown files, 13 packages had almost no visible doc entry point, and -131 packages still had doc-surface `TODO` or `undocumented` markers that need -triage. - -23. Expand landing pages and entry-point docs for low-surface distributed packages. - Paths: `M2/Macaulay2/packages/Browse.m2`, - `M2/Macaulay2/packages/Benchmark.m2`, - `M2/Macaulay2/packages/Dmodules.m2`, - `M2/Macaulay2/packages/Schubert2.m2`, - `M2/Macaulay2/packages/Schubert2/doc.m2`, - `M2/Macaulay2/packages/RationalPoints.m2`, - `M2/Macaulay2/packages/BeginningMacaulay2.m2`, - `M2/Macaulay2/packages/Serialization.m2`, - `M2/Macaulay2/packages/Units.m2`, - `M2/Macaulay2/packages/RandomCurves.m2`, - `M2/Macaulay2/packages/VectorGraphics.m2`, - `M2/Macaulay2/packages/WhitneyStratifications.m2`, - `M2/Macaulay2/packages/Msolve.m2` - Done when: each package has a visible overview or landing page, and the - user-facing packages in this group have at least one clear example or - tutorial path. - -24. Finish algebra and geometry package docs that still contain explicit TODO or undocumented placeholders. - Paths: `M2/Macaulay2/packages/LocalRings.m2`, - `M2/Macaulay2/packages/LocalRings/doc.m2`, - `M2/Macaulay2/packages/LocalRings/examples.m2`, - `M2/Macaulay2/packages/Saturation.m2`, - `M2/Macaulay2/packages/Saturation/doc.m2`, - `M2/Macaulay2/packages/Saturation/quotient-doc.m2`, - `M2/Macaulay2/packages/Saturation/saturate-doc.m2`, - `M2/Macaulay2/packages/MinimalPrimes.m2`, - `M2/Macaulay2/packages/MinimalPrimes/doc.m2`, - `M2/Macaulay2/packages/PrimaryDecomposition/doc.m2`, - `M2/Macaulay2/packages/PrimaryDecomposition/examples.m2`, - `M2/Macaulay2/packages/IntegralClosure.m2`, - `M2/Macaulay2/packages/Triangulations.m2`, - `M2/Macaulay2/packages/Truncations.m2`, - `M2/Macaulay2/packages/Truncations/docs.m2`, - `M2/Macaulay2/packages/Varieties/*.m2` - Done when: the explicit `TODO` and `undocumented` placeholders in these - package doc surfaces are either resolved or split into smaller tracked - issues, and navigation problems such as the orphan `quotient` node in - `Saturation/quotient-doc.m2` are fixed or documented. - -25. Finish interface and application package docs that still contain explicit TODO or undocumented placeholders. - Paths: `M2/Macaulay2/packages/SCSCP/docs.m2`, - `M2/Macaulay2/packages/SCSCP/examples.m2`, - `M2/Macaulay2/packages/Python/doc.m2`, - `M2/Macaulay2/packages/Python/doc/tutorials.m2`, - `M2/Macaulay2/packages/ReactionNetworks.m2`, - `M2/Macaulay2/packages/ReactionNetworks/Readme.md`, - `M2/Macaulay2/packages/Cremona/documentation.m2`, - `M2/Macaulay2/packages/NumericalAlgebraicGeometry/doc.m2`, - `M2/Macaulay2/packages/NumericalSchubertCalculus/README`, - `M2/Macaulay2/packages/Bertini/doc.m2`, - `M2/Macaulay2/packages/BernsteinSato/DOC/*.m2`, - `M2/Macaulay2/packages/VectorGraphics.m2`, - `M2/Macaulay2/packages/WhitneyStratifications.m2`, - `M2/Macaulay2/packages/Msolve.m2` - Done when: undocumented exports or explicit `TODO` notes in these package - docs are reduced, external prerequisites are explained where needed, and - the package docs give a clear starting point for first-time users. - -26. Curate package example and tutorial surfaces that are present but unfinished or hard to navigate. - Paths: `M2/Macaulay2/packages/LocalRings/examples.m2`, - `M2/Macaulay2/packages/PrimaryDecomposition/examples.m2`, - `M2/Macaulay2/packages/BernsteinSato/DOC/*.m2`, - `M2/Macaulay2/packages/Bertini/TST/*.tst.m2`, - `M2/Macaulay2/packages/NumericalAlgebraicGeometry/README`, - `M2/Macaulay2/packages/NumericalAlgebraicGeometry/TST/README.txt`, - `M2/Macaulay2/packages/Python/doc/tutorials.m2`, - `M2/Macaulay2/packages/ReactionNetworks/example*.m2`, - `M2/Macaulay2/packages/SCSCP/examples.m2`, - `M2/Macaulay2/packages/OldChainComplexes/docs/*.m2` - Done when: the example entry points in this set are labeled clearly as - tutorials, demos, or tests, obviously unfinished sections are completed or - trimmed, and readers can tell which files are meant to be read first. - -27. Record the first full distributed-package documentation audit and keep it split into follow-up waves. - Paths: `M2/Macaulay2/packages/=distributed-packages`, - `DocumentationPlan.md` - Done when: the audit results remain summarized in the plan with counts, and - the high-priority packages from that scan are represented by explicit - follow-up items instead of one umbrella note. - -### Tutorials, Examples, And Teaching Material - -28. Review `BeginningMacaulay2` as a first-user tutorial. - Paths: `M2/Macaulay2/packages/BeginningMacaulay2.m2`, - `M2/Macaulay2/packages/BeginningMacaulay2/tutorial` - Done when: the tutorial still works as a modern first stop for new users, - obvious stale workflow assumptions are corrected, and its role in the main - documentation navigation is clear. - -29. Refresh the commutative algebra tutorial set and its dated course framing. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/tu_elementary.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/loads.m2` - Done when: the `Fall 2005` / `Math 634` framing is either removed or - intentionally contextualized, tutorial titles and descriptions are clearer - for current users, and the exposed examples still make sense as entry - points. - -30. Refresh `Tutorial: Modules in Macaulay2`. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/tu_modules.m2` - Done when: stale references such as `Section XX` and speculative - future-behavior notes are removed or rewritten, and the tutorial still - reads coherently for users learning modules from examples. - -31. Refresh `Tutorial: Divisors`. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/tu_divisors.m2` - Done when: obsolete forward references such as the missing “next divisor - tutorial” and historical performance notes are removed or replaced, and the - stated scope matches current functionality. - -32. Audit the advanced geometry tutorials for clarity and dated assumptions. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/tu_canEmbed.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/tu_Fano.m2` - Done when: terminology, caveats, and example framing have been reviewed for - current readers, and any stale notes are split into follow-up issues or - fixed. - -33. Audit the Computations Book landing page. - Paths: `M2/Macaulay2/tests/ComputationsBook/README` - Done when: the top-level description, navigation, and reader expectations - are current. - -34. Review chapter-level Computations Book README files for stale terminology. - Paths: `M2/Macaulay2/tests/ComputationsBook/*/README` - Done when: terminology, chapter descriptions, and references are consistent - across the chapter folders. - -35. Verify a representative sample of tutorial examples. - Paths: selected files under `M2/Macaulay2/tests/ComputationsBook/` - Done when: issues are filed for broken, outdated, or confusing examples and - the verified sample is documented in the issue. - -### Core Language And Reference Documentation - -36. Audit core overview links, placeholders, and navigation gaps. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/ov_getting_started.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/ov_documentation.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/ov_ringmaps.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/ov_groebner_bases.m2` - Done when: top-level `TO` and `SeeAlso` targets have been spot-checked, - placeholder or commented-out navigation such as missing troubleshooting or - contributor entry points is either resolved or split into tracked follow-up - work, and any broken or stale links found in these core overview pages are - fixed or recorded. - -37. Triage the core function docs that are still explicitly marked `status: TODO`. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/functions/*-doc.m2` - Done when: the current `status: TODO` set has been reviewed, the most - important exported functions are grouped into actionable follow-up issues, - and the backlog distinguishes between missing coverage, thin coverage, and - pages that mostly need examples. - -38. Document exported text, rendering, and serialization methods that are still marked undocumented. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/functions/expression-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/hypertext-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/html-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/mathML-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/tex-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/texMath-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/toString-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/toExternalString-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/format-doc.m2` - Done when: exported methods in this cluster no longer rely on generic - `undocumented` placeholders, and the docs explain what these routines are - for with at least one concrete example or cross-reference per page. - -39. Document exported filesystem, REPL, and utility functions that still have TODO or undocumented coverage. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/functions/isDirectory-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/isRegularFile-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/readDirectory-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/readlink-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/realpath-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/removeDirectory-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/findSynonyms-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/isGlobalSymbol-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/use-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/net-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/peek-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/index-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/clean-doc.m2` - Done when: the exported utilities in this group have enough explanation and - examples to be discoverable from the docs without reading source, and - obvious TODO markers or undocumented method placeholders are removed. - -40. Document exported algebra, Gröbner, and linear-algebra functions that still have TODO or undocumented coverage. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/gb-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/gbRemove-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/forceGB-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/rank-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/SVD-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/eigenvalues-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/eigenvectors-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/mingens-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/degrees-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/someTerms-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/monomials-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/GF-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/pseudoRemainder-doc.m2` - Done when: this cluster of exported mathematical functions has been triaged - into concrete documentation fixes with examples where needed, and clearly - missing or placeholder pages are no longer hidden behind `status: TODO`. - -41. Expand thin explanations and examples in the core getting-started, debugging, and module docs. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/ov_getting_started.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/generators-doc.m2`, - `M2/Macaulay2/packages/Macaulay2Doc/functions/preimage-doc.m2` - Done when: the docs add the missing explanatory context called out in the - source comments, stale “needs upgrades” notes are resolved, and example - gaps such as the missing `preimage` example or the unsalvaged - `generators` examples are addressed. - -### Repository-Wide Cleanup - -42. Run a broken-link sweep across Markdown and README files. - Paths: repo-wide Markdown and README files, excluding third-party submodules - Done when: broken internal links, moved files, and stale external links are - fixed or captured in follow-up issues. - -43. Standardize branch-name and workflow references in docs. - Paths: repo-wide documentation files - Done when: references to outdated branch names or outdated GitHub workflows - are corrected where appropriate. - -44. Identify documentation that belongs in the repo instead of only on the wiki. - Paths: top-level docs and places that link heavily to the wiki - Done when: critical contributor guidance has a repo-local home or a tracked - follow-up issue. - -45. Create a `good-first-issue` wave for new documentation contributors. - Paths: GitHub issues and labels - Done when: at least five narrowly scoped doc issues are labeled and ready to - assign. - -### Project Infrastructure And Discoverability - -46. Add fast CI checks for documentation pull requests to `doc-updates`. - Paths: `.github/workflows/`, `.github/actions/`, contributor docs as needed - Done when: documentation PRs get a lightweight automated check for obvious - failures such as broken scoped doc builds, broken links or cross-references - in changed documentation, and basic text-level regressions without forcing - every PR through a full package-example or full-site rebuild. - -47. Audit undocumented exported symbols across distributed packages. - Paths: `M2/Macaulay2/packages/`, package export lists, generated docs as - needed - Done when: exported symbols lacking documentation are summarized in a - tracked report or split into child issues by package or topic, and the - backlog clearly distinguishes between intentionally undocumented internals - and user-facing exports that still need documentation. - -48. Standardize external prerequisite documentation across packages. - Paths: package landing pages, READMEs, and doc nodes for packages that rely - on external software or services - Done when: packages with external prerequisites describe those dependencies - in a consistent place and format, including how to install or verify the - prerequisite and what functionality depends on it. - -49. Improve concept-to-command discoverability in the documentation. - Paths: `M2/Macaulay2/packages/Macaulay2Doc/`, package landing pages, and - related navigation pages - Done when: users who know a mathematical object or task but not the - relevant Macaulay2 command have a clearer path through topic pages, - cross-references, or index-style guides to the right reference entries and - examples. - -50. Document how repository changes become updates on `macaulay2.com`. - Paths: repo-local contributor docs, release/deployment docs if present, and - upstream process references as needed - Done when: contributors can tell what must happen after a documentation PR - lands for the live website to change, including which steps are local to - the repo, which depend on upstream maintainers, and where deployment or - publishing responsibility currently lives. - -51. Define reviewer routing for package, tutorial, and math-heavy documentation changes. - Paths: repo-local contributor docs, labels, and review workflow docs - Done when: contributors know when to request package-owner review, - `needs-math-review`, example reruns, or editorial review, and the review - expectations are documented in one repo-local place rather than spread - across issue comments. - -## Notes For Leads - -1. Keep the integration branch stable enough that people can branch from it - without inheriting unrelated work. -2. Prefer issues with exact paths over issues framed as "improve docs". -3. If a task changes both mathematical content and prose, ask for math review - explicitly instead of assuming an editorial review is enough. diff --git a/M2/BUILD/README.md b/M2/BUILD/README.md index 39ce7fb7ff1..dfe6856b2c6 100644 --- a/M2/BUILD/README.md +++ b/M2/BUILD/README.md @@ -1,5 +1,6 @@ -See [INSTALL](../INSTALL) or [INSTALL-CMake.md](../INSTALL-CMake.md) for build -requirements and instructions. +See the [Macaulay2 wiki](https://github.com/Macaulay2/M2/wiki) for current +build requirements and instructions, especially the "Building M2 from source" +pages for the autotools and CMake workflows. This directory may be used as a convenient location for the build directory trees. For example, it may contain subdirectories `Linux-i686` and @@ -33,5 +34,5 @@ architecture-independent files are in a subdirectory of this directory called `common`, and the architecture-dependent files will be in other subdirectories, such as `x86_64-Linux-Ubuntu-8.10`. (Actually, this is being changed...) -Alternatively, see the [this guide](docker/README.md) for instructions on using -Docker to build Linux container images running Macaulay2. +Alternatively, see the [Docker guide](docker/README.md) for instructions on +using Docker to build Linux container images running Macaulay2. diff --git a/M2/Macaulay2/editors/README.md b/M2/Macaulay2/editors/README.md index 11b7407aa85..f1a9e206a46 100644 --- a/M2/Macaulay2/editors/README.md +++ b/M2/Macaulay2/editors/README.md @@ -1,22 +1,23 @@ # Macaulay2 editors -This directory contains template files used by the -[generateGrammar](https://macaulay2.com/doc/Macaulay2/share/doc/Macaulay2/Style/html/_generate__Grammar.html) function in the *Style* package to generate -grammar files used by various editors for syntax highlighting and automatic -completion of Macaulay2 code. +This directory contains the editor and syntax-highlighting assets that ship +with Macaulay2. The shared generator script is +[`make-M2-symbols.m2`](make-M2-symbols.m2); when run from this directory, it +rewrites the symbol files used by Emacs, Prism, Pygments, and Vim. -Each subdirectory contains one or more template files for a particular -application. +Each subdirectory documents a particular integration: -* [`emacs`](https://github.com/Macaulay2/M2-emacs): Symbols for GNU Emacs. -* [`prism`](prism): Symbols for the Prism Javascript library. These are used - for syntax highlighting the online Macaulay2 documentation. -* [`pygments`](pygments): Symbols for Pygments, a syntax highlighter written - in Python. -* [`vim`](vim): Symbols for the Vim editor. +* [`emacs/README.md`](emacs/README.md): running and editing Macaulay2 in GNU + Emacs, including the bundled support files. +* [`vim/README_linux`](vim/README_linux) and + [`vim/README_macos`](vim/README_macos): running Macaulay2 inside Vim on + GNU/Linux and macOS. +* [`prism/README.md`](prism/README.md): generating and using the Prism grammar + used for syntax highlighting the HTML documentation. +* [`pygments/README.md`](pygments/README.md): generating and using the Pygments + lexer. -Several template files that formerly were kept in this directory have since -been moved to their own repositories: +Several related integrations are maintained in standalone repositories: * highlight.js: https://github.com/d-torrance/highlightjs-macaulay2 * Linguist: https://github.com/Macaulay2/language-macaulay2 diff --git a/M2/Macaulay2/editors/prism/README.md b/M2/Macaulay2/editors/prism/README.md index d14ba2865c3..2621ff72a9d 100644 --- a/M2/Macaulay2/editors/prism/README.md +++ b/M2/Macaulay2/editors/prism/README.md @@ -9,13 +9,14 @@ used in [Macaulay2Web](https://github.com/pzinn/Macaulay2Web). Building -------- -To build only the Macaulay2 grammar, run the following: +To regenerate the Macaulay2 grammar from this repository, change to +`M2/Macaulay2/editors` and run: ``` -M2 --script /path/to/M2/Macaulay2/editors/make-M2-symbols +M2 --script make-M2-symbols.m2 ``` -This will generate the file `prism/macaulay2.js`. +This writes the file `prism/macaulay2.js`. Using ----- @@ -45,7 +46,7 @@ monomialCurveIdeal(R, {1, 2, 3}) Style package ------------- -The file `prism.js` included in Macaulay2's `Style` package the Prism +The file `prism.js` in Macaulay2's `Style` package bundles the Prism JavaScript and CSS files together with the Macaulay2 grammar using [node](https://nodejs.org/) and [webpack](https://webpack.js.org/). diff --git a/M2/Macaulay2/editors/pygments/README.md b/M2/Macaulay2/editors/pygments/README.md index d02fb21e867..dd5d1a97b6e 100644 --- a/M2/Macaulay2/editors/pygments/README.md +++ b/M2/Macaulay2/editors/pygments/README.md @@ -28,19 +28,17 @@ pygmentize -O full -o foo.html ``` If you have an older version of Pygments, or would like to generate the -Macaulay2 lexer yourself, run: - +Macaulay2 lexer yourself, change to `M2/Macaulay2/editors` and run: ``` -M2 --script /M2/Macaulay2/editors/make-M2-symbols.m2 +M2 --script make-M2-symbols.m2 ``` -The file `macaulay2.py` should appear in the `pygments` subdirectory of your -current directory. Then, if you want syntax highlighting for a Macaulay2 file, -you would run: +This writes the file `pygments/macaulay2.py`. Then, if you want syntax +highlighting for a Macaulay2 file with the generated lexer, run: ``` -cd pygments +cd /path/to/M2/Macaulay2/editors/pygments pygmentize -x -l macaulay2.py:Macaulay2Lexer ``` diff --git a/M2/Macaulay2/editors/vim/README_linux b/M2/Macaulay2/editors/vim/README_linux index 9793bfa95ea..bea8695f757 100644 --- a/M2/Macaulay2/editors/vim/README_linux +++ b/M2/Macaulay2/editors/vim/README_linux @@ -1,8 +1,8 @@ Author: Manoj Kummini -These are files useful for running M2 inside vim on a GNU/Linux machine. -These use the scripts by David Cook II (earlier available at -http://www.ms.uky.edu/~dcook/files/Macaulay2.vim). +These files are useful for running M2 inside Vim on a GNU/Linux machine. +They use a screen-based workflow and may require small local adjustments on +current systems. I. Required programmes @@ -12,7 +12,7 @@ I. Required programmes II. Files included - 0. 0README_linux (this file) + 0. README_linux (this file) 1. m2.vimrc (the RC file that sets the file-type, loads the dictionary file and the syntax file, etc.) @@ -26,9 +26,6 @@ be highlighted) 4. m2.vim.plugin (the main file that implements how M2 commands from the vim window is transferred to M2 running inside a screen session) - 5. VimM2.scpt (wrapper Apple script around Terminal.app to start the M2 -session inside a screen session) - III. Usage 1. copy m2.vimrc as $HOME/.vim/m2.vimrc, and source it from $HOME/.vimrc, preferably with @@ -41,7 +38,7 @@ III. Usage at the end. (vim did not recognize the file with the .syntax at the end; perhaps some option may be set to take care of this issue.) - 4. copy m2.vim.plugin as $HOME/.vim/plugin/m2.vim and as + 4. copy m2.vim.plugin as $HOME/.vim/plugin/m2.vim and as $HOME/.vim/ftplugin/m2.vim, without the .plugin at the end. (vim did not recognize the file with the .plugin at the end; perhaps some option may be set to take care of this issue. Further, depending on whether the filetype diff --git a/M2/Macaulay2/editors/vim/README_macos b/M2/Macaulay2/editors/vim/README_macos index 3824286696b..24faa97d10c 100644 --- a/M2/Macaulay2/editors/vim/README_macos +++ b/M2/Macaulay2/editors/vim/README_macos @@ -1,8 +1,8 @@ Author: Manoj Kummini These are files useful for running M2 inside vim on a Mac. These use the -scripts by David Cook II (earlier available at -http://www.ms.uky.edu/~dcook/files/Macaulay2.vim). +scripts by David Cook II. Some of these notes were written for older macOS +releases and may require small local adjustments on current systems. Disclaimer: I used these on Mac OS X Snow Leopard, but after switching to Linux, I have not modified these files for newer versions of OS X. @@ -15,7 +15,7 @@ I. Required programmes II. Files included - 0. 0README_macos (this file) + 0. README_macos (this file) 1. m2.vimrc (the RC file that sets the file-type, loads the dictionary file and the syntax file, etc.) @@ -44,7 +44,7 @@ III. Usage at the end. (vim did not recognize the file with the .syntax at the end; perhaps some option may be set to take care of this issue.) - 4. copy m2.vim.plugin as $HOME/.vim/plugin/m2.vim and as + 4. copy m2.vim.plugin as $HOME/.vim/plugin/m2.vim and as $HOME/.vim/ftplugin/m2.vim, without the .plugin at the end. (vim did not recognize the file with the .plugin at the end; perhaps some option may be set to take care of this issue. Further, depending on whether the filetype diff --git a/M2/Macaulay2/packages/BeginningMacaulay2.m2 b/M2/Macaulay2/packages/BeginningMacaulay2.m2 index 25429cad19e..100e2c5aafa 100644 --- a/M2/Macaulay2/packages/BeginningMacaulay2.m2 +++ b/M2/Macaulay2/packages/BeginningMacaulay2.m2 @@ -4,7 +4,7 @@ newPackage( "BeginningMacaulay2", Version => "1.0", Date => "November 3, 2009", {Name => "David Eisenbud", Email => "de@msri.org", HomePage => "http://www.msri.org/~de"}, {Name => "Mike Stillman", Email => "mike@math.cornell.edu", HomePage => "http://www.math.cornell.edu/~mike"} }, - Headline => "Mathematicians' Introduction to Macaulay2", + Headline => "introductory tutorial for new Macaulay2 users", Keywords => {"Documentation"}, PackageExports => {"Complexes"}, AuxiliaryFiles => true diff --git a/M2/Macaulay2/packages/BeginningMacaulay2/tutorial b/M2/Macaulay2/packages/BeginningMacaulay2/tutorial index f36888c113b..d39d10cfc2c 100644 --- a/M2/Macaulay2/packages/BeginningMacaulay2/tutorial +++ b/M2/Macaulay2/packages/BeginningMacaulay2/tutorial @@ -2,10 +2,11 @@ Key "BeginningMacaulay2" Headline - Mathematicians' Introduction to Macaulay2 + introductory tutorial for new Macaulay2 users Description Text - We assume you've installed {\em Macaulay2} and can type + This tutorial is a first stop for new users. We assume you've + installed {\em Macaulay2} and can type Code EXAMPLE { PRE ///M2/// } Text @@ -16,7 +17,7 @@ Description newline, "Type `help` to see useful commands")} Text We suggest you do that now, so that you can experiment while you read - this tutorial! + through the examples in this tutorial. Code diff --git a/M2/Macaulay2/packages/README b/M2/Macaulay2/packages/README index 771b3b678ae..3f1b9e71e3a 100644 --- a/M2/Macaulay2/packages/README +++ b/M2/Macaulay2/packages/README @@ -1,17 +1,29 @@ +Package documentation in this directory usually lives in the package file +`Foo.m2` and sometimes in an auxiliary directory `Foo/`. To browse the +distributed packages from within Macaulay2, use: + + help "packages provided with Macaulay2" + +To open a package landing page directly, use: + + viewHelp "Foo" + +If a package has additional auxiliary files, examples, or supporting data, they +will generally be stored in a directory whose name matches the package. + To add your package to Macaulay2: -First test that your package works by running "installPackage" and "check" on -it. View the documentation with "viewHelp" to make sure it looks sensible, +First test that your package works by running `installPackage` and `check` on +it. View the documentation with `viewHelp` to make sure it looks sensible, paging through each node by pressing the "next" button repeatedly. Then create an account on github.com and fork our repository -https://github.com/Macaulay2/M2, clone your copy of M2, and add your package -file to this "packages" directory, along with its directory of auxiliary files, -if any. Also add a line to the end of the file =distributed-packages -containing the name of your package. Add those changes, commit them, and push -them to your repository. Then on the github page for your copy of M2, push the -button called "Pull request". That will notify us that you'd like your -addition to become part of Macaulay2/M2. +https://github.com/Macaulay2/M2, clone your copy of the `development` branch of +M2, and add your package file to this "packages" directory, along with its +directory of auxiliary files, if any. Also add a line to the end of the file +`=distributed-packages` containing the name of your package. Add those +changes, commit them, and push them to your repository. Then open a pull +request against `Macaulay2/M2:development`. More advanced users will want to add their new package to a new branch of the repository. diff --git a/M2/README.md b/M2/README.md index 750cc831d9f..77746859bef 100644 --- a/M2/README.md +++ b/M2/README.md @@ -1,5 +1,7 @@ This directory is the top level of the Macaulay2 source tree. -See the [Wiki](https://github.com/Macaulay2/M2/wiki) for a variety of installation instructions and other information. - +See the [Wiki](https://github.com/Macaulay2/M2/wiki) for current installation +instructions, build guides, and contributor information. The "Building M2 from +source" section of the wiki is the current entry point for the autotools and +CMake build workflows. diff --git a/README.md b/README.md index 406cf043f3e..86c433f5a90 100644 --- a/README.md +++ b/README.md @@ -19,22 +19,24 @@ See `CITATION.cff` for information about citing Macaulay2. Contributions to the code of Macaulay2 are welcome. The source code is available via our GitHub [repository](https://github.com/Macaulay2/M2), where you can also report bugs via the [issue tracker](https://github.com/Macaulay2/M2/issues). -For general background on the upstream git workflow, see the -[Git for Macaulay2 Contributors](https://github.com/Macaulay2/M2/wiki/Git-for-Macaulay2-Contributors) -wiki page. +For the current contribution workflow, use the Macaulay2 wiki: -For the documentation refresh workflow on this fork: +* [Git for Macaulay2 Contributors](https://github.com/Macaulay2/M2/wiki/Git-for-Macaulay2-Contributors) +* [Pull requests](https://github.com/Macaulay2/M2/wiki/Pull-requests) -* Track work in the `aalmousa/M2` issues and the `M2 Documentation Refresh` - project. -* Branch from `doc-updates`. -* Open pull requests against `aalmousa/M2:doc-updates`, not `master`. +In brief: + +* Fork `Macaulay2/M2` and work from the `development` branch. +* Open pull requests against `Macaulay2/M2:development`. * State what you verified locally, especially for examples, links, and regenerated documentation pages. -See [DocumentationPlan.md](DocumentationPlan.md) and -[DocumentationGuide.md](DocumentationGuide.md) for the current documentation -workflow, contributor guidance, and documentation standards. +This fork may still be used to stage documentation-refresh work through +`aalmousa/M2` issues and project items, but upstream contributions land through +`Macaulay2/M2:development`. + +Changes in a repository branch do not appear on `macaulay2.com` until they are +merged upstream and published by the maintainers. To start working on an existing github "issue", volunteer to work on it, so you can get "assigned" to the issue, thereby preventing duplication of From 03b9a752a7829d34a9f70efed2742e282c4ac969 Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Tue, 19 May 2026 10:50:57 -0400 Subject: [PATCH 57/73] add assert --- M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 index 4f07cc69702..e03ed2db5bf 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 @@ -48,7 +48,8 @@ doc /// R = QQ[a..d]; S = QQ[s,t]; F = map(S,R,{s^3, s^2*t, s*t^2, t^3}) - ker(F, SubringLimit => 1) + K = ker(F, SubringLimit => 1) + assert(numgens K == 1) Text In the case when everything is homogeneous, Hilbert functions are used to speed up the computations. Caveat From 8dd8d472aa6f5afa3bcc045e9a4de91830163b7c Mon Sep 17 00:00:00 2001 From: aalmousa Date: Wed, 20 May 2026 09:26:11 -0400 Subject: [PATCH 58/73] docs: fix Galois field map docs --- M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 index bb8af3e14fb..d081ddc8bf7 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 @@ -5,7 +5,6 @@ doc /// Node Key - (map, GaloisField, GaloisField, List) (map, GaloisField, GaloisField) Headline maps of Galois fields @@ -22,7 +21,11 @@ Node carrying 1 to x Description Text - GF(p^n) contains GF(p^m) if and only if m divides n + GF(p^n) contains GF(p^m) if and only if m divides n. + Text + The specialized method documented here is @TT "map(F,G)"@. The + three-argument form @TT "map(F,G,x)"@ uses the generic ring-map + constructor, as in @TO (map,Ring,Ring,List)@. Example F4 = GF(2^2) F8 = GF(2^3) @@ -37,6 +40,7 @@ Node SeeAlso isWellDefined GF + (map,Ring,Ring,List) /// undocumented {(map, RingFamily, Thing, Thing),(map, Thing, RingFamily, Thing), From c74418fcdb8bb8ec15075df384d79e70d9bd0113 Mon Sep 17 00:00:00 2001 From: Joel Dodge Date: Tue, 19 May 2026 08:49:33 -0400 Subject: [PATCH 59/73] missed variable name change in tensor doc examples --- M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 index 331a5e656a4..be71b6f811b 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 @@ -470,7 +470,7 @@ doc /// R = kk[a, b, c] I = ideal (a, b); A = I/I^2 J = ideal (b, c); B = J/J^2 - K = ideal (a, c); F = K/K^2 + K = ideal (a, c); C = K/K^2 T = A_0 ** (B_0 ** C_0) T' = (A_0 ** B_0) ** C_0 assert(tensorAssociativity(A, B, C) * T == T') From 13b7379946ddd04b0dcd564e23adf400b345c979 Mon Sep 17 00:00:00 2001 From: klee669 Date: Wed, 20 May 2026 11:36:17 -0400 Subject: [PATCH 60/73] Update Macaulay2 package docs (gin, NAG) and map(GF,GF) documentation fixed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adjust documentation across Macaulay2 packages: - GenericInitialIdeal: extend the document Key for gin to include (gin,Ideal) and (gin,QuotientRing); comment out the separate document nodes for those keys to avoid duplication. - map-doc: tidy the Galois field map documentation—reorder explanations, move the three-argument form description, update the example to handle non-existing maps with a try/else, and add TO (map,GaloisField,GaloisField) to the list of documented signatures. - tu_NAG: add "NumericalSchubertCalculus" to the NAG package list. These are documentation-only changes to improve clarity and register additional interfaces. --- M2/Macaulay2/packages/GenericInitialIdeal.m2 | 8 +++++--- .../packages/Macaulay2Doc/functions/map-doc.m2 | 13 ++++++------- M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 | 1 + 3 files changed, 12 insertions(+), 10 deletions(-) diff --git a/M2/Macaulay2/packages/GenericInitialIdeal.m2 b/M2/Macaulay2/packages/GenericInitialIdeal.m2 index efaa1772695..f08479d0c11 100644 --- a/M2/Macaulay2/packages/GenericInitialIdeal.m2 +++ b/M2/Macaulay2/packages/GenericInitialIdeal.m2 @@ -131,7 +131,9 @@ with high probability, they give the correct answer, but it could be the case th -- 20/07/2018 Lorenzo: documentation updated with the multigraded gin document { - Key => {gin}, + Key => {gin, + (gin,Ideal), + (gin,QuotientRing)}, Headline => "the generic initial ideal", Usage => " gin I", Inputs => {"I" => {"an ", TO Ideal, " in a polynomial", TO Ring}, @@ -172,8 +174,8 @@ document { --These are documented in the above node. undocumented { "AttemptCount", "Modular", "Multigraded" } -document { Key => {(gin,Ideal)}, } -document { Key => {(gin,QuotientRing)}, } +--document { Key => {(gin,Ideal)}, } +--document { Key => {(gin,QuotientRing)}, } document { Key => {lexgin}, diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 index d081ddc8bf7..96d7ba33bbf 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 @@ -10,11 +10,9 @@ Node maps of Galois fields Usage phi = map(F,G) - phi = map(F,G,x) Inputs F:GaloisField G:GaloisField - x:List one element of F generating a subfield isomorphic to G Outputs phi:RingMap @@ -23,17 +21,17 @@ Node Text GF(p^n) contains GF(p^m) if and only if m divides n. Text - The specialized method documented here is @TT "map(F,G)"@. The - three-argument form @TT "map(F,G,x)"@ uses the generic ring-map - constructor, as in @TO (map,Ring,Ring,List)@. + The specialized method documented here is @TT "map(F,G)"@. Example F4 = GF(2^2) F8 = GF(2^3) F16 = GF(2^4) map(F16, F4) - map(F16, F8) + try map(F16, F8) else "1" -- there is no map of these fields exist, so returns 1 Text - It is possible to "define a map" that is not well-defined: + The three-argument form @TT "map(F,G,x)"@ uses the generic ring-map + constructor, as in @TO (map,Ring,Ring,List)@. + Also, it is possible to "define a map" that is not well-defined: Example phi = map(F16, F4, {1}) isWellDefined phi @@ -85,6 +83,7 @@ document { TO (map,Module,Module,RingMap,Matrix), "Creating a map between rings", TO (map,Ring,Ring), + TO (map,GaloisField,GaloisField), TO (map,Ring,Ring,List), TO (map,Ring,Ring,Matrix), -- "Creating a map between chain complexes", diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 b/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 index e2f5379f4a0..236d58655c0 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 @@ -262,5 +262,6 @@ Node "MonodromySolver" "NumericalCertification" "NumericalImplicitization" + "NumericalSchubertCalculus" /// From 283a9cfddac0939a90a54ddf1bb5b7ce18da14fb Mon Sep 17 00:00:00 2001 From: aalmousa Date: Wed, 20 May 2026 12:00:17 -0400 Subject: [PATCH 61/73] docs: split tutorials and restructure top-level navigation --- M2/Macaulay2/packages/=distributed-packages | 1 + .../functions/Grassmannian-doc.m2 | 2 +- .../Macaulay2Doc/functions/map-doc.m2 | 23 +- M2/Macaulay2/packages/Macaulay2Doc/loads.m2 | 30 -- .../Macaulay2Doc/ov_analytic_functions.m2 | 24 +- .../packages/Macaulay2Doc/ov_examples.m2 | 445 +++++------------- .../packages/Macaulay2Doc/ov_modules.m2 | 2 +- M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 | 194 +++++--- M2/Macaulay2/packages/Tutorials.m2 | 76 +++ .../packages/Tutorials/teaching_materials.m2 | 18 + .../{Macaulay2Doc => Tutorials}/tu_Fano.m2 | 0 .../{Macaulay2Doc => Tutorials}/tu_NAG.m2 | 0 .../tu_canEmbed.m2 | 0 .../tu_divisors.m2 | 0 .../tu_elementary.m2 | 0 .../tu_elementary1.m2 | 0 .../{Macaulay2Doc => Tutorials}/tu_modules.m2 | 0 17 files changed, 378 insertions(+), 437 deletions(-) create mode 100644 M2/Macaulay2/packages/Tutorials.m2 create mode 100644 M2/Macaulay2/packages/Tutorials/teaching_materials.m2 rename M2/Macaulay2/packages/{Macaulay2Doc => Tutorials}/tu_Fano.m2 (100%) rename M2/Macaulay2/packages/{Macaulay2Doc => Tutorials}/tu_NAG.m2 (100%) rename M2/Macaulay2/packages/{Macaulay2Doc => Tutorials}/tu_canEmbed.m2 (100%) rename M2/Macaulay2/packages/{Macaulay2Doc => Tutorials}/tu_divisors.m2 (100%) rename M2/Macaulay2/packages/{Macaulay2Doc => Tutorials}/tu_elementary.m2 (100%) rename M2/Macaulay2/packages/{Macaulay2Doc => Tutorials}/tu_elementary1.m2 (100%) rename M2/Macaulay2/packages/{Macaulay2Doc => Tutorials}/tu_modules.m2 (100%) diff --git a/M2/Macaulay2/packages/=distributed-packages b/M2/Macaulay2/packages/=distributed-packages index 25c732be3b0..625890b1595 100644 --- a/M2/Macaulay2/packages/=distributed-packages +++ b/M2/Macaulay2/packages/=distributed-packages @@ -62,6 +62,7 @@ ConvexInterface SRdeformations NumericalAlgebraicGeometry BeginningMacaulay2 +Tutorials FormalGroupLaws Graphics WeylGroups diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/Grassmannian-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/Grassmannian-doc.m2 index 4f0bb8f1e2b..2d0497957f9 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/Grassmannian-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/Grassmannian-doc.m2 @@ -111,6 +111,6 @@ document { ), SeeAlso => { Grassmannian, - "Tutorial: Fano varieties" + "Tutorials::Tutorial: Fano varieties" } } diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 index 96d7ba33bbf..d9d2a4d65c9 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 @@ -13,25 +13,32 @@ Node Inputs F:GaloisField G:GaloisField - one element of F generating a subfield isomorphic to G Outputs phi:RingMap - carrying 1 to x + the canonical inclusion of G into a compatible subfield of F Description Text GF(p^n) contains GF(p^m) if and only if m divides n. Text The specialized method documented here is @TT "map(F,G)"@. Example + F2 = GF 2 F4 = GF(2^2) F8 = GF(2^3) F16 = GF(2^4) + map(F16, F2) map(F16, F4) - try map(F16, F8) else "1" -- there is no map of these fields exist, so returns 1 Text - The three-argument form @TT "map(F,G,x)"@ uses the generic ring-map - constructor, as in @TO (map,Ring,Ring,List)@. - Also, it is possible to "define a map" that is not well-defined: + If no compatible subfield exists, then Macaulay2 signals an error: + Example + try map(F16, F8) else "this map does not exist" + Text + It is also possible to invoke the generic ring-map constructor with an + explicit image for a generator of the source field: + Example + map(F16, F4, {1}) + Text + Such a map need not be well-defined: Example phi = map(F16, F4, {1}) isWellDefined phi @@ -79,11 +86,11 @@ document { TO (map,Module,Nothing,Matrix), "Creating a map with a different degree", TO (map,Matrix), - "Creating a map between modules over different rings", + "Creating a map between modules over different rings", TO (map,Module,Module,RingMap,Matrix), "Creating a map between rings", - TO (map,Ring,Ring), TO (map,GaloisField,GaloisField), + TO (map,Ring,Ring), TO (map,Ring,Ring,List), TO (map,Ring,Ring,Matrix), -- "Creating a map between chain complexes", diff --git a/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 b/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 index 737bf2a5ee7..330664179dd 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 @@ -65,33 +65,3 @@ load "./doc_atomic.m2" load "./doc_mutex.m2" load "./options.m2" -- this must come last load "./undocumented.m2" - -load "./M2-Singular-Book.m2" - -ld := fn -> tutorial get concatenate(currentFileDirectory,fn) - -document { - Key => "Tutorial: Modules in Macaulay2", - ld "tu_modules.m2" - } -document { - Key => "Tutorial: Elementary uses of Gröbner bases", - ld "tu_elementary.m2" - } -document { - Key => "Tutorial: Canonical Embeddings of Plane Curves and Gonality", - ld "tu_canEmbed.m2" - } -document { - Key => "Tutorial: Divisors", - ld "tu_divisors.m2" - } -document { - Key => {"Elementary uses of Groebner bases I", "Elementary uses of Groebner bases I. Math 634 Fall 2005"}, - ld "tu_elementary1.m2" - } -document { - Key => "Tutorial: Fano varieties", - ld "tu_Fano.m2" - } -load "./tu_NAG.m2" diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_analytic_functions.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_analytic_functions.m2 index 71ba5976647..33f911d9fad 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_analytic_functions.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_analytic_functions.m2 @@ -22,20 +22,16 @@ Node Analytic functions in Macaulay2 include symbolic constants, special functions, trigonometric functions, and numerical evaluations over the standard inexact number types. - Tree - :Selected Packages - > @TOH "EllipticIntegrals :: EllipticIntegrals"@ - > @TOH "FormalGroupLaws :: FormalGroupLaws"@ - > @TOH "EllipticCurves :: EllipticCurves"@ - > @TOH "NumericalAlgebraicGeometry :: NumericalAlgebraicGeometry"@ - > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ - :Core topics - > "Constant" - > "Gamma" - > "zeta" - > "sin" - > "cos" - > "atan2" + Text + Selected packages include @TO2("EllipticIntegrals :: EllipticIntegrals", "EllipticIntegrals")@, + @TO2("FormalGroupLaws :: FormalGroupLaws", "FormalGroupLaws")@, + @TO2("EllipticCurves :: EllipticCurves", "EllipticCurves")@, and + @TO2("NumericalAlgebraicGeometry :: NumericalAlgebraicGeometry", "NumericalAlgebraicGeometry")@. + For a broader catalog, see + @TO2("packages provided with Macaulay2", "packages provided with Macaulay2")@. + Text + Core topics include @TO "Constant"@, @TO "Gamma"@, @TO "zeta"@, + @TO "sin"@, @TO "cos"@, and @TO "atan2"@. SeeAlso "packages provided with Macaulay2" "EllipticIntegrals :: EllipticIntegrals" diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 index 10ae4b047bf..2bf1bd5952c 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 @@ -6,20 +6,16 @@ Node Text Elementary arithmetic in Macaulay2 includes integer and modular arithmetic, factorization, gcd/lcm computations, and finite-field calculations. - Tree - :Selected Packages - > @TOH "ConwayPolynomials :: ConwayPolynomials"@ - > @TOH "Cyclotomic :: Cyclotomic"@ - > @TOH "LLLBases :: LLLBases"@ - > @TOH "EllipticCurves :: EllipticCurves"@ - > @TOH "Units :: Units"@ - > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ - :Core topics - > "gcd" - > "lcm" - > "factor" - > "powermod" - > "mod" + Text + Selected packages include @TO2("ConwayPolynomials :: ConwayPolynomials", "ConwayPolynomials")@, + @TO2("Cyclotomic :: Cyclotomic", "Cyclotomic")@, + @TO2("LLLBases :: LLLBases", "LLLBases")@, + @TO2("EllipticCurves :: EllipticCurves", "EllipticCurves")@, and + @TO2("Units :: Units", "Units")@. For a broader catalog, see + @TO2("packages provided with Macaulay2", "packages provided with Macaulay2")@. + Text + Core topics include @TO "gcd"@, @TO "lcm"@, @TO "factor"@, + @TO "powermod"@, and @TO "mod"@. SeeAlso "packages provided with Macaulay2" "ConwayPolynomials :: ConwayPolynomials" @@ -27,19 +23,6 @@ Node "LLLBases :: LLLBases" "EllipticCurves :: EllipticCurves" "Units :: Units" - Subnodes - mod - plus - minus - difference - times - power - powermod - (sqrt, ZZ, ZZ) - lcm - gcd - gcdCoefficients - factor Node Key @@ -49,41 +32,19 @@ Node Linear algebra in Macaulay2 includes matrix construction, determinants and minors, row reduction, matrix decompositions, kernels and inverses, and related multilinear constructions. - Tree - :Selected Packages - > @TOH "LLLBases :: LLLBases"@ - > @TOH "TensorComplexes :: TensorComplexes"@ - > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ - :Core topics - > "matrix" - > "determinants and minors" - > "rank" - > @TOH "kernel(Matrix)"@ - > @TOH "inverse(Matrix)"@ - > "transpose" - > "reducedRowEchelonForm" - > "LUdecomposition" - > "QRDecomposition" - > "SVD" - > "smithNormalForm" + Text + Selected packages include @TO2("LLLBases :: LLLBases", "LLLBases")@ and + @TO2("TensorComplexes :: TensorComplexes", "TensorComplexes")@. For a broader + catalog, see @TO2("packages provided with Macaulay2", "packages provided with Macaulay2")@. + Text + Core topics include @TO "matrix"@, @TO "determinants and minors"@, + @TO "rank"@, @TO "kernel(Matrix)"@, @TO "inverse(Matrix)"@, + @TO "transpose"@, @TO "reducedRowEchelonForm"@, @TO "LUdecomposition"@, + @TO "QRDecomposition"@, @TO "SVD"@, and @TO "smithNormalForm"@. SeeAlso "packages provided with Macaulay2" "LLLBases :: LLLBases" "TensorComplexes :: TensorComplexes" - Subnodes - @TO "LLLBases :: LLLBases"@ - @TO "TensorComplexes :: TensorComplexes"@ - matrix - "determinants and minors" - rank - "kernel(Matrix)" - "inverse(Matrix)" - transpose - reducedRowEchelonForm - LUdecomposition - QRDecomposition - SVD - smithNormalForm Node Key @@ -92,37 +53,32 @@ Node Text Commutative algebra in Macaulay2 centers on ideals, modules, Groebner bases, syzygies, Hilbert invariants, elimination, and resolution techniques. - Tree - :Tutorials - > "Tutorial: Modules in Macaulay2" - > "Tutorial: Elementary uses of Gröbner bases" - > "Teaching Materials" - :Selected Packages - > @TOH "IntegralClosure :: IntegralClosure"@ - > @TOH "PrimaryDecomposition :: PrimaryDecomposition"@ - > @TOH "ReesAlgebra :: ReesAlgebra"@ - > @TOH "MinimalPrimes :: MinimalPrimes"@ - > @TOH "Depth :: Depth"@ - > @TOH "Elimination :: Elimination"@ - > @TOH "Saturation :: Saturation"@ - > @TOH "Regularity :: Regularity"@ - > @TOH "LocalRings :: LocalRings"@ - > @TOH "MonomialAlgebras :: MonomialAlgebras"@ - > @TOH "NoetherNormalization :: NoetherNormalization"@ - > @TOH "TangentCone :: TangentCone"@ - > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ - :Core topics - > "Gröbner bases" - > "normal forms" - > "elimination of variables" - > "hilbertFunction" - > "hilbertSeries" - > "hilbertPolynomial" - > @TOH "Complexes :: freeResolution"@ - > @TOH "MinimalPrimes :: radical"@ - > @TOH "MinimalPrimes :: minimalPrimes"@ - > @TOH "PrimaryDecomposition :: primaryDecomposition"@ - > "regularity" + Text + Tutorials include @TO2("Tutorials::Tutorial: Modules in Macaulay2", "Tutorial: Modules in Macaulay2")@, + @TO2("Tutorials::Tutorial: Elementary uses of Gröbner bases", "Tutorial: Elementary uses of Gröbner bases")@, + and @TO2("Tutorials::Teaching Materials", "Teaching Materials")@. + Text + Selected packages include @TO2("IntegralClosure :: IntegralClosure", "IntegralClosure")@, + @TO2("PrimaryDecomposition :: PrimaryDecomposition", "PrimaryDecomposition")@, + @TO2("ReesAlgebra :: ReesAlgebra", "ReesAlgebra")@, + @TO2("MinimalPrimes :: MinimalPrimes", "MinimalPrimes")@, + @TO2("Depth :: Depth", "Depth")@, + @TO2("Elimination :: Elimination", "Elimination")@, + @TO2("Saturation :: Saturation", "Saturation")@, + @TO2("Regularity :: Regularity", "Regularity")@, + @TO2("LocalRings :: LocalRings", "LocalRings")@, + @TO2("MonomialAlgebras :: MonomialAlgebras", "MonomialAlgebras")@, + @TO2("NoetherNormalization :: NoetherNormalization", "NoetherNormalization")@, and + @TO2("TangentCone :: TangentCone", "TangentCone")@. For a broader catalog, see + @TO2("packages provided with Macaulay2", "packages provided with Macaulay2")@. + Text + Core topics include @TO "Gröbner bases"@, @TO "normal forms"@, + @TO "elimination of variables"@, @TO "hilbertFunction"@, + @TO "hilbertSeries"@, @TO "hilbertPolynomial"@, + @TO "Complexes :: freeResolution"@, @TO "MinimalPrimes :: radical"@, + @TO "MinimalPrimes :: minimalPrimes"@, + @TO "PrimaryDecomposition :: primaryDecomposition"@, and + @TO "regularity"@. Text The reference links below are retained for direct access to lower-level commands. SeeAlso @@ -136,56 +92,6 @@ Node "Saturation :: Saturation" "Regularity :: Regularity" "LocalRings :: LocalRings" - Subnodes - "Gröbner bases" - "normal forms" - -- Mike wanted this: TO "Hilbert functions" - "elimination of variables" - -- Mike wanted this: TO "syzygies" - -- Mike wanted this: TO "saturation" - -- Mike wanted this: TO "fibers of a map between varieties" - -- Mike wanted this: TO "solving systems of polynomial equations" - -- - @TO "IntegralClosure :: IntegralClosure"@ - @TO "PrimaryDecomposition :: PrimaryDecomposition"@ - -- - hilbertFunction - hilbertSeries - hilbertPolynomial - syz - koszul - eagonNorthcott - regularity - presentation - "OldChainComplexes :: resolution" - quotient - quotient' - quotientRemainder - quotientRemainder' - remainder - remainder' - pseudoRemainder - rank - dim - codim - pdim - depth -- contains link to package Depth - height -- TODO - length - complete - trim - prune - numgens - mingens - minimize - minimalPresentation - tensor - directSum - directProduct - monomialCurveIdeal - isBorel - isCommutative - isAffineRing Node Key @@ -195,28 +101,23 @@ Node Homological algebra in Macaulay2 covers complexes, maps of complexes, homology and cohomology functors, and derived constructions such as Tor and Ext. - Tree - :Tutorials - > "Tutorial: Modules in Macaulay2" - :Selected Packages - > @TOH "Complexes :: Complexes"@ - > @TOH "OldChainComplexes :: OldChainComplexes"@ - > @TOH "ChainComplexExtras :: ChainComplexExtras"@ - > @TOH "DGAlgebras :: DGAlgebras"@ - > @TOH "TorAlgebra :: TorAlgebra"@ - > @TOH "SchurFunctors :: SchurFunctors"@ - > @TOH "TensorComplexes :: TensorComplexes"@ - > @TOH "MCMApproximations :: MCMApproximations"@ - > @TOH "KustinMiller :: KustinMiller"@ - > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ - :Core topics - > "Tor" - > "Ext" - > "HH" - > "isExact" - > "kernel" - > "cokernel" - > "image" + Text + A good starting tutorial is + @TO2("Tutorials::Tutorial: Modules in Macaulay2", "Tutorial: Modules in Macaulay2")@. + Text + Selected packages include @TO2("Complexes :: Complexes", "Complexes")@, + @TO2("OldChainComplexes :: OldChainComplexes", "OldChainComplexes")@, + @TO2("ChainComplexExtras :: ChainComplexExtras", "ChainComplexExtras")@, + @TO2("DGAlgebras :: DGAlgebras", "DGAlgebras")@, + @TO2("TorAlgebra :: TorAlgebra", "TorAlgebra")@, + @TO2("SchurFunctors :: SchurFunctors", "SchurFunctors")@, + @TO2("TensorComplexes :: TensorComplexes", "TensorComplexes")@, + @TO2("MCMApproximations :: MCMApproximations", "MCMApproximations")@, and + @TO2("KustinMiller :: KustinMiller", "KustinMiller")@. For a broader catalog, see + @TO2("packages provided with Macaulay2", "packages provided with Macaulay2")@. + Text + Core topics include @TO "Tor"@, @TO "Ext"@, @TO "HH"@, + @TO "isExact"@, @TO "kernel"@, @TO "cokernel"@, and @TO "image"@. SeeAlso "packages provided with Macaulay2" "Complexes :: Complexes" @@ -227,26 +128,6 @@ Node "SchurFunctors :: SchurFunctors" "TensorComplexes :: TensorComplexes" "MCMApproximations :: MCMApproximations" - Subnodes - kernel - cokernel - image - coimage - preimage - pullback - pushout - extend - "OldChainComplexes :: nullhomotopy" - isExact - isInjective - isSurjective - isIsomorphism - inverse - ScriptedFunctor - id - HH - Tor - Ext Node Key @@ -256,30 +137,26 @@ Node Algebraic geometry in Macaulay2 includes computations with affine and projective varieties, toric and Schubert geometry, singularities, characteristic classes, and rational points. - Tree - :Tutorials - > "Tutorial: Divisors" - > "Tutorial: Canonical Embeddings of Plane Curves and Gonality" - > "Tutorial: Fano varieties" - :Selected Packages - > @TOH "Varieties :: Varieties"@ - > @TOH "Schubert2 :: Schubert2"@ - > @TOH "NormalToricVarieties :: NormalToricVarieties"@ - > @TOH "CharacteristicClasses :: CharacteristicClasses"@ - > @TOH "HyperplaneArrangements :: HyperplaneArrangements"@ - > @TOH "Points :: Points"@ - > @TOH "RationalPoints :: RationalPoints"@ - > @TOH "PushForward :: PushForward"@ - > @TOH "ToricVectorBundles :: ToricVectorBundles"@ - > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ - :Core topics - > "singularLocus" - > "Grassmannian" - > "Schubert" - > "Fano" - > "isNormal" - > "isSmooth" - > "genus" + Text + Tutorials include @TO2("Tutorials::Tutorial: Divisors", "Tutorial: Divisors")@, + @TO2("Tutorials::Tutorial: Canonical Embeddings of Plane Curves and Gonality", "Tutorial: Canonical Embeddings of Plane Curves and Gonality")@, + and @TO2("Tutorials::Tutorial: Fano varieties", "Tutorial: Fano varieties")@. + Text + Selected packages include @TO2("Varieties :: Varieties", "Varieties")@, + @TO2("Schubert2 :: Schubert2", "Schubert2")@, + @TO2("NormalToricVarieties :: NormalToricVarieties", "NormalToricVarieties")@, + @TO2("CharacteristicClasses :: CharacteristicClasses", "CharacteristicClasses")@, + @TO2("HyperplaneArrangements :: HyperplaneArrangements", "HyperplaneArrangements")@, + @TO2("Points :: Points", "Points")@, + @TO2("RationalPoints :: RationalPoints", "RationalPoints")@, + @TO2("PushForward :: PushForward", "PushForward")@, and + @TO2("ToricVectorBundles :: ToricVectorBundles", "ToricVectorBundles")@. + For a broader catalog, see + @TO2("packages provided with Macaulay2", "packages provided with Macaulay2")@. + Text + Core topics include @TO "singularLocus"@, @TO "Grassmannian"@, + @TO "Schubert"@, @TO "Fano"@, @TO "isNormal"@, + @TO "isSmooth"@, and @TO "genus"@. Text The reference links below remain available for direct access to core geometry commands. SeeAlso @@ -291,20 +168,6 @@ Node "HyperplaneArrangements :: HyperplaneArrangements" "RationalPoints :: RationalPoints" "ToricVectorBundles :: ToricVectorBundles" - Subnodes - singularLocus - Grassmannian - Schubert - Fano - isNormal - isSmooth - isVeryAmple - randomKRationalPoint - chi - euler - eulers - genus - genera Node Key @@ -315,31 +178,30 @@ Node functions, Schur and Weyl functors, Lie algebras and their representations, highest-weight methods, group actions, invariant theory, and related character computations. - Tree - :Selected Packages - > @TOH "SchurRings :: SchurRings"@ - > @TOH "SchurFunctors :: SchurFunctors"@ - > @TOH "PieriMaps::PieriMaps"@ - > @TOH "WeylGroups :: WeylGroups"@ - > @TOH "LieAlgebraRepresentations :: LieAlgebraRepresentations"@ - > @TOH "GradedLieAlgebras :: GradedLieAlgebras"@ - > @TOH "HighestWeights :: HighestWeights"@ - > @TOH "InvariantRing :: InvariantRing"@ - > @TOH "BettiCharacters :: BettiCharacters"@ - > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ - :Core topics - > @TOH "SchurFunctors :: schur"@ - > @TOH "SchurFunctors :: schurModule"@ - > @TOH "SchurRings :: plethysm"@ - > @TOH "SchurRings :: internalProduct"@ - > @TOH "LieAlgebraRepresentations :: simpleLieAlgebra"@ - > @TOH "HighestWeights :: setWeights"@ - > @TO2("HighestWeights :: HighestWeights", "highest-weight decompositions")@ - > @TO2("InvariantRing :: InvariantRing", "group actions and invariant rings")@ - > @TO2("BettiCharacters :: BettiCharacters", "characters on resolutions and graded modules")@ - > @TOH "WeylGroups :: rootSystem"@ - > @TOH "WeylGroups :: dynkinType"@ - > @TOH "WeylGroups :: cartanMatrix"@ + Text + Selected packages include @TO2("SchurRings :: SchurRings", "SchurRings")@, + @TO2("SchurFunctors :: SchurFunctors", "SchurFunctors")@, + @TO2("PieriMaps::PieriMaps", "PieriMaps")@, + @TO2("WeylGroups :: WeylGroups", "WeylGroups")@, + @TO2("LieAlgebraRepresentations :: LieAlgebraRepresentations", "LieAlgebraRepresentations")@, + @TO2("GradedLieAlgebras :: GradedLieAlgebras", "GradedLieAlgebras")@, + @TO2("HighestWeights :: HighestWeights", "HighestWeights")@, + @TO2("InvariantRing :: InvariantRing", "InvariantRing")@, and + @TO2("BettiCharacters :: BettiCharacters", "BettiCharacters")@. For a broader + catalog, see @TO2("packages provided with Macaulay2", "packages provided with Macaulay2")@. + Text + Core topics include @TO "SchurFunctors :: schur"@, + @TO "SchurFunctors :: schurModule"@, + @TO "SchurRings :: plethysm"@, + @TO "SchurRings :: internalProduct"@, + @TO "LieAlgebraRepresentations :: simpleLieAlgebra"@, + @TO "HighestWeights :: setWeights"@, + @TO2("HighestWeights :: HighestWeights", "highest-weight decompositions")@, + @TO2("InvariantRing :: InvariantRing", "group actions and invariant rings")@, + @TO2("BettiCharacters :: BettiCharacters", "characters on resolutions and graded modules")@, + @TO "WeylGroups :: rootSystem"@, + @TO "WeylGroups :: dynkinType"@, and + @TO "WeylGroups :: cartanMatrix"@. Text The reference links below remain available for direct access to package entry points and core constructions. @@ -354,25 +216,6 @@ Node "HighestWeights :: HighestWeights" "InvariantRing :: InvariantRing" "BettiCharacters :: BettiCharacters" - Subnodes - @TO "SchurRings :: SchurRings"@ - @TO "SchurFunctors :: SchurFunctors"@ - @TO "PieriMaps::PieriMaps"@ - @TO "WeylGroups :: WeylGroups"@ - @TO "LieAlgebraRepresentations :: LieAlgebraRepresentations"@ - @TO "GradedLieAlgebras :: GradedLieAlgebras"@ - @TO "HighestWeights :: HighestWeights"@ - @TO "InvariantRing :: InvariantRing"@ - @TO "BettiCharacters :: BettiCharacters"@ - "SchurFunctors :: schur" - "SchurFunctors :: schurModule" - "SchurRings :: plethysm" - "SchurRings :: internalProduct" - "LieAlgebraRepresentations :: simpleLieAlgebra" - "HighestWeights :: setWeights" - "WeylGroups :: rootSystem" - "WeylGroups :: dynkinType" - "WeylGroups :: cartanMatrix" Node Key @@ -381,31 +224,26 @@ Node Text Combinatorics in Macaulay2 spans graphs, posets, simplicial complexes, polyhedra, lattice polytopes, and combinatorial commutative algebra. - Tree - :Selected Packages - > @TOH "Graphs :: Graphs"@ - > @TOH "Posets :: Posets"@ - > @TOH "Matroids :: Matroids"@ - > @TOH "EdgeIdeals :: EdgeIdeals"@ - > @TOH "SimplicialComplexes :: SimplicialComplexes"@ - > @TOH "Polyhedra :: Polyhedra"@ - > @TOH "LatticePolytopes :: LatticePolytopes"@ - > @TOH "StatePolytope :: StatePolytope"@ - > @TOH "Nauty :: Nauty"@ - > @TOH "NautyGraphs :: NautyGraphs"@ - > @TOH "FourTiTwo :: FourTiTwo"@ - > @TOH "Normaliz :: Normaliz"@ - > @TOH "SimplicialDecomposability :: SimplicialDecomposability"@ - > @TO2("packages provided with Macaulay2", "browse packages by subject area")@ - :Core topics - > "partitions" - > "compositions" - > "binomial" - > "Set" - > "cone" - > "rays" - > "normalCone" - > "multidegree" + Text + Selected packages include @TO2("Graphs :: Graphs", "Graphs")@, + @TO2("Posets :: Posets", "Posets")@, + @TO2("Matroids :: Matroids", "Matroids")@, + @TO2("EdgeIdeals :: EdgeIdeals", "EdgeIdeals")@, + @TO2("SimplicialComplexes :: SimplicialComplexes", "SimplicialComplexes")@, + @TO2("Polyhedra :: Polyhedra", "Polyhedra")@, + @TO2("LatticePolytopes :: LatticePolytopes", "LatticePolytopes")@, + @TO2("StatePolytope :: StatePolytope", "StatePolytope")@, + @TO2("Nauty :: Nauty", "Nauty")@, + @TO2("NautyGraphs :: NautyGraphs", "NautyGraphs")@, + @TO2("FourTiTwo :: FourTiTwo", "FourTiTwo")@, + @TO2("Normaliz :: Normaliz", "Normaliz")@, and + @TO2("SimplicialDecomposability :: SimplicialDecomposability", "SimplicialDecomposability")@. + For a broader catalog, see + @TO2("packages provided with Macaulay2", "packages provided with Macaulay2")@. + Text + Core topics include @TO "partitions"@, @TO "compositions"@, + @TO "binomial"@, @TO "Set"@, @TO "cone"@, @TO "rays"@, + @TO "normalCone"@, and @TO "multidegree"@. SeeAlso "packages provided with Macaulay2" "Graphs :: Graphs" @@ -416,35 +254,4 @@ Node "LatticePolytopes :: LatticePolytopes" "Nauty :: Nauty" "FourTiTwo :: FourTiTwo" - Subnodes - binomial - compositions - inversePermutation - partitions - random - shuffle - Set - rays - cone - normalCone - multidegree /// - -document { - Key => {"Teaching Materials", "A first course in commutative algebra"}, - "This section collects teaching materials and introductory tutorials - for basic commutative algebra in Macaulay2, at roughly the level of - Atiyah-Macdonald and Greuel-Pfister.", - PARA{}, - "Use these materials when you want worked examples that connect - commutative-algebra topics to first Macaulay2 commands, including - Gröbner bases, ideals and modules, Hilbert invariants, elimination, - and resolutions.", - PARA{}, - "Macaulay2 examples corresponding to examples in the Greuel-Pfister - text may also be found here.", - Subnodes => { - TO2("Elementary uses of Groebner bases I", "Elementary uses of Groebner bases"), - TO "M2SingularBook" - } - } diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 index 7e9d6216690..9dacabcb8e4 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 @@ -5,7 +5,7 @@ document { Submodules and quotients of free modules are perhaps the most common and important modules, and subquotients form the smallest class of modules that naturally includes these cases.", PARA{}, - "See ", TO "Tutorial: Modules in Macaulay2", " for an overview tutorial on modules.", + "See ", TO "Tutorials::Tutorial: Modules in Macaulay2", " for an overview tutorial on modules.", PARA{}, "Common module tasks usually start with one of the following pages or commands.", UL { diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 index 5d0beebfde7..d0595486b47 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 @@ -12,72 +12,21 @@ Node Text Macaulay2 is an interpreted, dynamically typed programming language designed to support research in commutative algebra, algebraic geometry, and related fields. - This documentation includes getting-started guides, language and reference material, - tutorials, and package documentation for the packages distributed with Macaulay2. + This documentation includes getting-started guides, package and language documentation, + mathematical reference material, tutorials, and developer-facing documentation. Text If you are new to Macaulay2, start with @TO "setting up Macaulay2"@, @TO "a first Macaulay2 session"@, and @TO "reading the documentation"@. - If you know the mathematical object or computation you want, use the - Mathematical Objects and Mathematical Computations sections below to move - from concepts such as rings, ideals, matrices, modules, Gröbner bases, - Hilbert functions, and resolutions to the corresponding commands and examples. - For package-level tools, start with @TO2("packages", "loading and using packages")@ - or @TO2("packages provided with Macaulay2", "browsing packages by subject area")@. + Use the sections below to move from learning the system, to working with + packages and the language, to guided mathematical examples and subject-area + references, to developer and internal documentation. For longer walkthroughs, + start with @TO2("Tutorials::Tutorials", "Tutorials")@. Tree - :Getting Started - > "setting up Macaulay2" - > "a first Macaulay2 session" - > "reading the documentation" - > "getting help or reporting bugs" - :Practical Guides - > "The Macaulay2 language" - > @TO2("packages", "loading and using packages")@ - > @TO2("packages provided with Macaulay2", "browsing packages by subject area")@ - > "debugging" - > "the debugger" - > "error handling" - :Mathematical Tutorials - -- These tutorials begin with broader introductions and continue with - -- more specialized worked examples in algebra and geometry. - > "Tutorial: Modules in Macaulay2" - > "Tutorial: Elementary uses of Gröbner bases" - > "Tutorial: Divisors" - > "Tutorial: Canonical Embeddings of Plane Curves and Gonality" - > "Tutorial: Fano varieties" - > "Tutorial: Numerical algebraic geometry" - > "Teaching Materials" - :Mathematical Objects - > "rings" - > "ideals" - > "matrices" - > "modules" - > @TO2(map, "morphisms")@ - > @TO2("Complexes :: Complexes", "chain complexes")@ (also see @TO2("OldChainComplexes :: OldChainComplexes", "legacy version")@) - > @TO2("Varieties :: Varieties", "varieties and sheaves")@ - > @TO2("Graphs :: Graphs", "graphs")@ - > @TO2("Posets :: Posets", "posets")@ - > @TO2("SimplicialComplexes :: SimplicialComplexes", "simplicial complexes")@ - > @TO2("Polyhedra :: Polyhedra", "polyhedra")@ - :Mathematical Computations - > @TO2("elementary arithmetic", "Elementary Arithmetic")@ - > @TO2("linear algebra", "Linear Algebra")@ - > @TO2("commutative algebra", "Commutative Algebra")@ - > @TO2("homological algebra", "Homological Algebra")@ - > @TO2("algebraic geometry", "Algebraic Geometry")@ - > "Representation Theory" - > @TO2("combinatorics", "Combinatorics")@ - > @TO2("analytic functions", "Analytic Functions")@ - Tree - :Appendix - > "changes to Macaulay2, by version" - -- Mike wanted this: TO "frequently encountered problems" - > "replacements for commands and scripts from Macaulay" - Acknowledgement - Tree - > "Acknowledgements" - > "The authors of Macaulay2" - > "The authors of Macaulay2 packages" - > "Copyright and license" + > "Start Here" + > "Using Macaulay2" + > "Doing Mathematics" + > "For Developers" + > "About" Contributors Contributors to Macaulay2 documentation include Daniel Grayson, Michael Stillman, Mahrud Sayrafi, Doug Torrance, Paul Zinn-Justin, Lily Silverstein, Frédéric Chapoton, @@ -86,9 +35,8 @@ Node Boyana Martinova, Eliana Duarte, Lars Kastner, and Kisun Lee; additional names credited in documentation files outside git history include Sorin Popescu, Manoj Kummini, Leah Gold, Amelia Taylor, Giulio Caviglia, Gregory G. Smith, Wolfram Decker, - Jonah Blasiak, Josephine Yu, and Irena Peeva. + Jonah Blasiak, Josephine Yu, Irena Peeva, and Joel Dodge. References - -- TODO: node to be written, will point to our book, Hal's book, Mike's Arizona notes, Sage, etc: @UL { LI { HREF{"https://macaulay2.com/", "Macaulay2.com"}, " website, for online documentation, binary distributions, etc." }, LI { SPAN "Computations in algebraic geometry with Macaulay2, @@ -103,6 +51,124 @@ Node }@ /// +document { + Key => "Start Here", + "Start here if you are new to Macaulay2 or want the basic entry points for + installing it, starting a session, navigating the documentation, and finding help.", + Subnodes => { + TO "setting up Macaulay2", + TO "a first Macaulay2 session", + TO "reading the documentation", + TO "getting help or reporting bugs" + } + } + +document { + Key => "Using Macaulay2", + "This section routes you into the language, package workflow, and the most + common practical topics for daily use.", + PARA{}, + UL { + TO "The Macaulay2 language", + TO "packages", + TO "packages provided with Macaulay2", + TO "debugging", + TO "error handling" + }, + Subnodes => { + TO "The Macaulay2 language", + TO "packages provided with Macaulay2" + } + } + +document { + Key => "Doing Mathematics", + "This section groups the tutorial landing page together with the main + subject-area overview pages for objects and computations.", + Subnodes => { + TO "Tutorials and Examples", + TO "By object", + TO "By computation" + } + } + +document { + Key => "Tutorials and Examples", + "This page gathers the longer guided walkthroughs, teaching materials, and + other tutorial-style entry points.", + Subnodes => { + TO "Tutorials::Tutorials" + } + } + +document { + Key => "By object", + "These overview pages are organized by the kind of mathematical object you + are working with.", + Subnodes => { + TO "rings", + TO "ideals", + TO "matrices", + TO "modules", + TO "morphisms", + TO "Complexes :: Complexes", + TO "Varieties :: Varieties", + TO "Graphs :: Graphs", + TO "Posets :: Posets", + TO "SimplicialComplexes :: SimplicialComplexes", + TO "Polyhedra :: Polyhedra" + } + } + +document { + Key => "By computation", + "These overview pages are organized by the kind of computation you want to + perform.", + Subnodes => { + TO "elementary arithmetic", + TO "linear algebra", + TO "commutative algebra", + TO "homological algebra", + TO "algebraic geometry", + TO "Representation Theory", + TO "combinatorics", + TO "analytic functions" + } + } + +document { + Key => "For Developers", + "This section routes to package-authoring, documentation, debugging, and + internal implementation material without changing the underlying ownership + of those nodes.", + PARA{}, + UL { + TO "creating a package", + TO "writing documentation", + TO "debugging", + TO "error handling", + TO "Macaulay2Doc::Core", + TO "how Macaulay2 finds its files", + TO "the interpreter of Macaulay2", + TO "the engine of Macaulay2", + TO "parallelism in engine computations" + } + } + +document { + Key => "About", + "This section collects acknowledgements, authorship, licensing, version + history, and legacy material related to Macaulay2.", + Subnodes => { + TO "Acknowledgements", + TO "The authors of Macaulay2", + TO "The authors of Macaulay2 packages", + TO "Copyright and license", + TO "changes to Macaulay2, by version", + TO "replacements for commands and scripts from Macaulay" + } + } + end-- restart diff --git a/M2/Macaulay2/packages/Tutorials.m2 b/M2/Macaulay2/packages/Tutorials.m2 new file mode 100644 index 00000000000..4540e66b57b --- /dev/null +++ b/M2/Macaulay2/packages/Tutorials.m2 @@ -0,0 +1,76 @@ +newPackage ("Tutorials", + Version => version#"VERSION", + Headline => "tutorials and teaching materials for Macaulay2", + HomePage => "https://macaulay2.com/", + Authors => { -* see the contributors listed on the main page *- }, + Keywords => { "Documentation" }, + InfoDirSection => "Macaulay2 and its packages", + AuxiliaryFiles => true +) + +beginDocumentation() + +doc /// +Node + Key + "Tutorials" + Headline + curated tutorials and teaching materials for Macaulay2 + Description + Text + This package collects Macaulay2's longer guided tutorials and teaching + materials in one place. + Text + Use these pages when you want a sustained walkthrough rather than a + reference entry for a single command or package. The @TO "Macaulay2Doc::Macaulay2"@ + front page and the subject-area pages in @TO "Macaulay2Doc::commutative algebra"@ + and @TO "Macaulay2Doc::algebraic geometry"@ also link to the individual tutorials + most relevant to each area. + Tree + :Foundational tutorials + > "Tutorial: Modules in Macaulay2" + > "Tutorial: Elementary uses of Gröbner bases" + > "Teaching Materials" + :Geometry tutorials + > "Tutorial: Divisors" + > "Tutorial: Canonical Embeddings of Plane Curves and Gonality" + > "Tutorial: Fano varieties" + :Numerical tutorial + > "Tutorial: Numerical algebraic geometry" +/// + +ld := fn -> tutorial get (currentFileDirectory|"Tutorials/"|fn) + +document { + Key => "Tutorial: Modules in Macaulay2", + ld "tu_modules.m2" + } +document { + Key => "Tutorial: Elementary uses of Gröbner bases", + ld "tu_elementary.m2" + } +document { + Key => "Tutorial: Canonical Embeddings of Plane Curves and Gonality", + ld "tu_canEmbed.m2" + } +document { + Key => "Tutorial: Divisors", + ld "tu_divisors.m2" + } +document { + Key => {"Elementary uses of Groebner bases I", "Elementary uses of Groebner bases I. Math 634 Fall 2005"}, + ld "tu_elementary1.m2" + } +document { + Key => "Tutorial: Fano varieties", + ld "tu_Fano.m2" + } +load "./Tutorials/tu_NAG.m2" +load "./Macaulay2Doc/M2-Singular-Book.m2" +load "./Tutorials/teaching_materials.m2" + +end + +-- Local Variables: +-- compile-command: "make -C $M2BUILDDIR/Macaulay2/packages PACKAGES=Tutorials RemakeAllDocumentation=true IgnoreExampleErrors=false" +-- End: diff --git a/M2/Macaulay2/packages/Tutorials/teaching_materials.m2 b/M2/Macaulay2/packages/Tutorials/teaching_materials.m2 new file mode 100644 index 00000000000..d6df33d821e --- /dev/null +++ b/M2/Macaulay2/packages/Tutorials/teaching_materials.m2 @@ -0,0 +1,18 @@ +document { + Key => {"Teaching Materials", "A first course in commutative algebra"}, + "This section collects teaching materials and introductory tutorials + for basic commutative algebra in Macaulay2, at roughly the level of + Atiyah-Macdonald and Greuel-Pfister.", + PARA{}, + "Use these materials when you want worked examples that connect + commutative-algebra topics to first Macaulay2 commands, including + Gröbner bases, ideals and modules, Hilbert invariants, elimination, + and resolutions.", + PARA{}, + "Macaulay2 examples corresponding to examples in the Greuel-Pfister + text may also be found here.", + Subnodes => { + TO2("Elementary uses of Groebner bases I", "Elementary uses of Groebner bases"), + TO "M2SingularBook" + } + } diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_Fano.m2 b/M2/Macaulay2/packages/Tutorials/tu_Fano.m2 similarity index 100% rename from M2/Macaulay2/packages/Macaulay2Doc/tu_Fano.m2 rename to M2/Macaulay2/packages/Tutorials/tu_Fano.m2 diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 b/M2/Macaulay2/packages/Tutorials/tu_NAG.m2 similarity index 100% rename from M2/Macaulay2/packages/Macaulay2Doc/tu_NAG.m2 rename to M2/Macaulay2/packages/Tutorials/tu_NAG.m2 diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_canEmbed.m2 b/M2/Macaulay2/packages/Tutorials/tu_canEmbed.m2 similarity index 100% rename from M2/Macaulay2/packages/Macaulay2Doc/tu_canEmbed.m2 rename to M2/Macaulay2/packages/Tutorials/tu_canEmbed.m2 diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_divisors.m2 b/M2/Macaulay2/packages/Tutorials/tu_divisors.m2 similarity index 100% rename from M2/Macaulay2/packages/Macaulay2Doc/tu_divisors.m2 rename to M2/Macaulay2/packages/Tutorials/tu_divisors.m2 diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_elementary.m2 b/M2/Macaulay2/packages/Tutorials/tu_elementary.m2 similarity index 100% rename from M2/Macaulay2/packages/Macaulay2Doc/tu_elementary.m2 rename to M2/Macaulay2/packages/Tutorials/tu_elementary.m2 diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_elementary1.m2 b/M2/Macaulay2/packages/Tutorials/tu_elementary1.m2 similarity index 100% rename from M2/Macaulay2/packages/Macaulay2Doc/tu_elementary1.m2 rename to M2/Macaulay2/packages/Tutorials/tu_elementary1.m2 diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_modules.m2 b/M2/Macaulay2/packages/Tutorials/tu_modules.m2 similarity index 100% rename from M2/Macaulay2/packages/Macaulay2Doc/tu_modules.m2 rename to M2/Macaulay2/packages/Tutorials/tu_modules.m2 From a6a5a7f0c9d5e60ae9ded941de1c5c89e36b558a Mon Sep 17 00:00:00 2001 From: klee669 Date: Wed, 20 May 2026 13:34:35 -0400 Subject: [PATCH 62/73] Enhance NAG tutorial intro and outline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a detailed introduction and explicit section outline to M2/Macaulay2/packages/Tutorials/tu_NAG.m2. The tutorial now includes an overview and lists sections A–E (Homotopy continuation; Witness sets and numerical irreducible decomposition; Monodromy method; Numerical certification; Numerical implicitization), plus minor formatting adjustments before the existing quick-start text. --- M2/Macaulay2/packages/Tutorials/tu_NAG.m2 | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/M2/Macaulay2/packages/Tutorials/tu_NAG.m2 b/M2/Macaulay2/packages/Tutorials/tu_NAG.m2 index 236d58655c0..6a22f22dfd3 100644 --- a/M2/Macaulay2/packages/Tutorials/tu_NAG.m2 +++ b/M2/Macaulay2/packages/Tutorials/tu_NAG.m2 @@ -6,7 +6,26 @@ Node Numerical algebraic geometry Description Text - @BOLD "Quick start: Solving a system of equations"@ + In this tutorial we introduce basics of numerical algebraic geometry + to solve systems of polynomial equations, and useful numerical Macaulay2 packages. + The sections are: + + A. Homotopy continuation + + B. Witness sets and numerical irreducible decomposition + + C. Monodromy method + + D. Numerical certification + + E. Numerical implicitization + + + + + + Text + @BOLD "Quick start: Solving a system of equations"@ Suppose that you would like to solve a system of polynomial equations (polynomial system). Using Macaulay2, one can simply run the following: From 7e3ad40b665fbc2429f5fd59d14f14a0a5aab479 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Thu, 21 May 2026 10:37:43 -0400 Subject: [PATCH 63/73] docs: fix Macaulay2Doc doc tree and map docs --- .../Macaulay2Doc/functions/kernel-doc.m2 | 101 ++++----- .../Macaulay2Doc/functions/map-doc.m2 | 85 ++++---- .../packages/Macaulay2Doc/ov_debugging.m2 | 60 +---- .../packages/Macaulay2Doc/ov_examples.m2 | 94 ++++++++ .../packages/Macaulay2Doc/ov_lists.m2 | 3 + .../packages/Macaulay2Doc/ov_ringmaps.m2 | 7 +- M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 | 206 +++++------------- 7 files changed, 263 insertions(+), 293 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 index e03ed2db5bf..90a88eb6ad5 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 @@ -15,56 +15,6 @@ Node syz /// -doc /// - Key - (kernel, RingMap) - Headline - kernel of a ringmap - Usage - kernel f - Inputs - f:RingMap - $f: R \rightarrow S$ - SubringLimit => ZZ - stop the computation after this many elements of the kernel have been found. - DegreeLimit => ZZ - stop the computation after generators for the kernel in this degree have been found - Strategy => String - Groebner basis computation strategy. See @TO gb@. - Outputs - :Ideal - an ideal of $R$ - Description - Text - The twisted cubic. - Example - R = QQ[a..d]; - S = QQ[s,t]; - F = map(S,R,{s^3, s^2*t, s*t^2, t^3}) - ker F - Text - Passing @TT "SubringLimit"@ stops the computation early. - Example - R = QQ[a..d]; - S = QQ[s,t]; - F = map(S,R,{s^3, s^2*t, s*t^2, t^3}) - K = ker(F, SubringLimit => 1) - assert(numgens K == 1) - Text - In the case when everything is homogeneous, Hilbert functions are used to speed up the computations. - Caveat - It should be possible to interrupt the computation and restart it, but this has not yet been implemented. - SeeAlso - "substitution and maps between rings" - "elimination of variables" - monomialCurveIdeal - Subnodes - kernel - SubringLimit - DegreeLimit - Strategy -/// - document { Key => {(kernel,Matrix), (kernel, RingElement)}, @@ -141,3 +91,54 @@ Caveat SeeAlso gb /// + + +doc /// + Key + (kernel, RingMap) + Headline + kernel of a ringmap + Usage + kernel f + Inputs + f:RingMap + $f: R \rightarrow S$ + SubringLimit => ZZ + stop the computation after this many elements of the kernel have been found. + DegreeLimit => ZZ + stop the computation after generators for the kernel in this degree have been found + Strategy => String + Groebner basis computation strategy. See @TO gb@. + Outputs + :Ideal + an ideal of $R$ + Description + Text + The twisted cubic. + Example + R = QQ[a..d]; + S = QQ[s,t]; + F = map(S,R,{s^3, s^2*t, s*t^2, t^3}) + ker F + Text + Passing @TT "SubringLimit"@ stops the computation early. + Example + R = QQ[a..d]; + S = QQ[s,t]; + F = map(S,R,{s^3, s^2*t, s*t^2, t^3}) + K = ker(F, SubringLimit => 1) + assert(numgens K == 1) + Text + In the case when everything is homogeneous, Hilbert functions are used to speed up the computations. + Caveat + It should be possible to interrupt the computation and restart it, but this has not yet been implemented. + SeeAlso + "substitution and maps between rings" + "elimination of variables" + monomialCurveIdeal + Subnodes + kernel + "kernel(...,SubringLimit=>...)" + "kernel(...,DegreeLimit=>...)" + "kernel(...,Strategy=>...)" +/// diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 index d9d2a4d65c9..cf1393f18c8 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 @@ -2,51 +2,46 @@ --- author(s): --- notes: -doc /// -Node - Key - (map, GaloisField, GaloisField) - Headline - maps of Galois fields - Usage - phi = map(F,G) - Inputs - F:GaloisField - G:GaloisField - Outputs - phi:RingMap - the canonical inclusion of G into a compatible subfield of F - Description - Text - GF(p^n) contains GF(p^m) if and only if m divides n. - Text - The specialized method documented here is @TT "map(F,G)"@. - Example - F2 = GF 2 - F4 = GF(2^2) - F8 = GF(2^3) - F16 = GF(2^4) - map(F16, F2) - map(F16, F4) - Text - If no compatible subfield exists, then Macaulay2 signals an error: - Example - try map(F16, F8) else "this map does not exist" - Text - It is also possible to invoke the generic ring-map constructor with an - explicit image for a generator of the source field: - Example - map(F16, F4, {1}) - Text - Such a map need not be well-defined: - Example - phi = map(F16, F4, {1}) - isWellDefined phi - SeeAlso - isWellDefined - GF - (map,Ring,Ring,List) -/// +document { + Key => (map, GaloisField, GaloisField), + Headline => "maps of Galois fields", + Usage => "phi = map(F,G)", + Inputs => { + "F" => GaloisField, + "G" => GaloisField + }, + Outputs => { + RingMap => {"the canonical inclusion of ", TT "G", " into a compatible subfield of ", TT "F"} + }, + "GF(p^n) contains GF(p^m) if and only if ", TT "m", " divides ", TT "n", ".", + "The specialized method documented here is ", TT "map(F,G)", ".", + EXAMPLE { + "F2 = GF 2", + "F4 = GF(2^2)", + "F8 = GF(2^3)", + "F16 = GF(2^4)", + "map(F16, F2)", + "map(F16, F4)" + }, + "If no compatible subfield exists, then Macaulay2 signals an error:", + EXAMPLE { + "try map(F16, F8) else \"this map does not exist\"" + }, + "It is also possible to invoke the generic ring-map constructor with an explicit image for a generator of the source field:", + EXAMPLE { + "map(F16, F4, {1})" + }, + "Such a map need not be well-defined:", + EXAMPLE { + "phi = map(F16, F4, {1})", + "isWellDefined phi" + }, + SeeAlso => { + isWellDefined, + GF, + (map,Ring,Ring,List) + } + } undocumented {(map, RingFamily, Thing, Thing),(map, Thing, RingFamily, Thing), (map, RingFamily, Thing), (map, Thing, RingFamily)} diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 index 062f6b27a9a..8d46c297d8c 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 @@ -195,55 +195,17 @@ document { "One useful way to debug code suspected of being in error is to insert an explicit error message, such as ", TT ///error "debug me"///, ", and start stepping from there, as in the following demonstration." }, - EXAMPLE PRE /// -i1 : load "Macaulay2Doc/demos/demo2.m2" - -i2 : code f - -o2 = .../Macaulay2Doc/demos/demo2.m2:6:4-12:6 - : --source code: - f = t -> ( - x := 1; - error "debug me"; - y := t+1; - z := 1/t; - w := x+t; - ) - -i3 : f 0 -.../Macaulay2Doc/demos/demo2.m2:8:10:(3):[1]: error: debug me -.../Macaulay2Doc/demos/demo2.m2:8:10:(3): entering debugger - -ii4 : return -.../Macaulay2Doc/demos/demo2.m2:9:11:(3):[1]: --stepping limit reached -.../Macaulay2Doc/demos/demo2.m2:9:11:(3): entering debugger - -ii5 : current - -oo5 = local-assign 2 0 2-OP + local-fetch 0 0 - 1 - -oo5 : PseudocodeClosure - -ii6 : disassemble oo - -oo6 = (local-assign 2 0 (2-OP + (local-fetch 0 0) 1)) - -ii7 : step(-3) -.../Macaulay2Doc/demos/demo2.m2:9:11:(3):[1]: --evaluating: (local-assign 2 0 (2-OP + (local-fetch 0 0) 1)) -.../Macaulay2Doc/demos/demo2.m2:9:11:(3):[1]: --evaluating: (2-OP + (local-fetch 0 0) 1) -.../Macaulay2Doc/demos/demo2.m2:9:10:(3):[1]: --evaluating: (local-fetch 0 0) -.../Macaulay2Doc/demos/demo2.m2:9:12:(3):[1]: --stepping limit reached - -ii8 : step -.../Macaulay2Doc/demos/demo2.m2:10:11:(3):[1]: --stepping limit reached - -ii9 : step -.../Macaulay2Doc/demos/demo2.m2:10:11:(3):[1]: error: division by zero - -ii10 : t - -oo10 = 0 + EXAMPLE lines /// + load "Macaulay2Doc/demos/demo2.m2" + code f + f 0 + return + current + disassemble oo + step(-3) + step + step + t ///, SeeAlso => { "debugging" } } diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 index 2bf1bd5952c..5ac23338363 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 @@ -23,6 +23,26 @@ Node "LLLBases :: LLLBases" "EllipticCurves :: EllipticCurves" "Units :: Units" + Subnodes + gcd + lcm + factor + gcdCoefficients + powermod + mod + quotient + quotient' + quotientRemainder + quotientRemainder' + remainder + remainder' + pseudoRemainder + plus + minus + times + power + (sqrt,ZZ,ZZ) + random Node Key @@ -45,6 +65,10 @@ Node "packages provided with Macaulay2" "LLLBases :: LLLBases" "TensorComplexes :: TensorComplexes" + Subnodes + id + inverse + rank Node Key @@ -92,6 +116,28 @@ Node "Saturation :: Saturation" "Regularity :: Regularity" "LocalRings :: LocalRings" + Subnodes + codim + dim + depth + height + "Gröbner bases" + "normal forms" + "elimination of variables" + hilbertFunction + hilbertSeries + hilbertPolynomial + regularity + mingens + minimalPresentation + minimize + monomialCurveIdeal + numgens + pdim + trim + isAffineRing + isBorel + isCommutative Node Key @@ -128,6 +174,26 @@ Node "SchurFunctors :: SchurFunctors" "TensorComplexes :: TensorComplexes" "MCMApproximations :: MCMApproximations" + Subnodes + cokernel + complete + directSum + eagonNorthcott + Ext + extend + HH + image + isExact + isInjective + isIsomorphism + isSurjective + koszul + presentation + prune + ScriptedFunctor + syz + tensor + Tor Node Key @@ -168,6 +234,23 @@ Node "HyperplaneArrangements :: HyperplaneArrangements" "RationalPoints :: RationalPoints" "ToricVectorBundles :: ToricVectorBundles" + Subnodes + chi + euler + eulers + Fano + genera + genus + Grassmannian + isNormal + isSmooth + isVeryAmple + preimage + pullback + pushout + randomKRationalPoint + Schubert + singularLocus Node Key @@ -254,4 +337,15 @@ Node "LatticePolytopes :: LatticePolytopes" "Nauty :: Nauty" "FourTiTwo :: FourTiTwo" + Subnodes + binomial + compositions + cone + directProduct + inversePermutation + multidegree + normalCone + partitions + rays + Set /// diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_lists.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_lists.m2 index a09cb053d19..543507d2eed 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_lists.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_lists.m2 @@ -442,6 +442,7 @@ doc/// MutableList :Information about lists (length, VisibleList) + length (symbol #, List) isEmpty :Accessing list elements @@ -503,6 +504,7 @@ doc/// (symbol +, List, List) (symbol -, List, List) (symbol |, List, List) + difference join append prepend @@ -522,6 +524,7 @@ doc/// mergePairs reverse sequence + shuffle unsequence switch tally diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_ringmaps.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_ringmaps.m2 index b433f8cc873..b2dd710af55 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_ringmaps.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_ringmaps.m2 @@ -78,8 +78,7 @@ document { TO (symbol **, RingMap, Module) }, Subnodes => { - TO (symbol SPACE, RingMap, RingElement), - TO (kernel, RingMap), + TO (symbol SPACE, RingMap, RingElement), TO (source, RingMap), TO (target, RingMap), TO (symbol ^, RingMap, ZZ), @@ -403,6 +402,10 @@ document { graphIdeal, graphRing, "elimination of variables" + }, + Subnodes => { + TO (kernel, RingMap), + TO coimage } } undocumented { diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 index d0595486b47..7c9e27f2d0f 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 @@ -17,158 +17,70 @@ Node Text If you are new to Macaulay2, start with @TO "setting up Macaulay2"@, @TO "a first Macaulay2 session"@, and @TO "reading the documentation"@. - Use the sections below to move from learning the system, to working with - packages and the language, to guided mathematical examples and subject-area + Use the expanded sections below to move from learning the system, to working + with packages and the language, to guided mathematical examples and subject-area references, to developer and internal documentation. For longer walkthroughs, start with @TO2("Tutorials::Tutorials", "Tutorials")@. Tree - > "Start Here" - > "Using Macaulay2" - > "Doing Mathematics" - > "For Developers" - > "About" - Contributors - Contributors to Macaulay2 documentation include Daniel Grayson, Michael Stillman, - Mahrud Sayrafi, Doug Torrance, Paul Zinn-Justin, Lily Silverstein, Frédéric Chapoton, - Zach Teitler, Anton Leykin, Guillem Blanco, Dave Barton, Brian Pike, Michael Burr, - Frank Moore, Fatemeh Tarashi, Dylan Peifer, Thomas Kahle, Marc Harkonen, David Eisenbud, - Boyana Martinova, Eliana Duarte, Lars Kastner, and Kisun Lee; additional names credited - in documentation files outside git history include Sorin Popescu, Manoj Kummini, - Leah Gold, Amelia Taylor, Giulio Caviglia, Gregory G. Smith, Wolfram Decker, - Jonah Blasiak, Josephine Yu, Irena Peeva, and Joel Dodge. - References - @UL { - LI { HREF{"https://macaulay2.com/", "Macaulay2.com"}, " website, for online documentation, binary distributions, etc." }, - LI { SPAN "Computations in algebraic geometry with Macaulay2, - Algorithms and Computations in Mathematics (No. 8), - edited by David Eisenbud, Daniel R. Grayson, Michael E. Stillman, and Bernd Sturmfels, - Springer-Verlag, 2001, ISBN 3-540-42230-7." }, - LI { SPAN "Computational Algebraic Geometry, - London Mathematical Society Student Texts (No. 58), - by Hal Schenck, - Cambridge University Press, 2003 - ISBN: 0-521-53650-2." } - }@ + :Start Here + > "setting up Macaulay2" + > "a first Macaulay2 session" + > "reading the documentation" + > "getting help or reporting bugs" + :Using Macaulay2 + > "The Macaulay2 language" + * "lists and sequences" + * "packages" + > "packages provided with Macaulay2" + :Doing Mathematics + :Tutorials and Examples + * "Tutorials::Tutorials" + :By Area + > "elementary arithmetic" + > "linear algebra" + > "commutative algebra" + > "homological algebra" + > "algebraic geometry" + > "Representation Theory" + > "combinatorics" + > "analytic functions" + :By Mathematical Object + > "rings" + > "ideals" + > "matrices" + > "modules" + > "morphisms" + > "Complexes :: Complexes" + > "Varieties :: Varieties" + > "Graphs :: Graphs" + > "Posets :: Posets" + > "SimplicialComplexes :: SimplicialComplexes" + > "Polyhedra :: Polyhedra" + :For Developers + * "creating a package" + * "writing documentation" + * "debugging" + * "error handling" + * "Macaulay2Doc::Core" + * "how Macaulay2 finds its files" + * "the interpreter of Macaulay2" + * "the engine of Macaulay2" + * "parallelism in engine computations" + :About + > "Acknowledgements" + > "The authors of Macaulay2" + > "The authors of Macaulay2 packages" + > "Copyright and license" + > "changes to Macaulay2, by version" + > "replacements for commands and scripts from Macaulay" + :Contributors + :Contributors to Macaulay2 documentation include Daniel Grayson, Michael Stillman, Mahrud Sayrafi, Doug Torrance, Paul Zinn-Justin, Lily Silverstein, Frédéric Chapoton, Zach Teitler, Anton Leykin, Guillem Blanco, Dave Barton, Brian Pike, Michael Burr, Frank Moore, Fatemeh Tarashi, Dylan Peifer, Thomas Kahle, Marc Harkonen, David Eisenbud, Boyana Martinova, Eliana Duarte, Lars Kastner, and Kisun Lee; additional names credited in documentation files outside git history include Sorin Popescu, Manoj Kummini, Leah Gold, Amelia Taylor, Giulio Caviglia, Gregory G. Smith, Wolfram Decker, Jonah Blasiak, Josephine Yu, Irena Peeva, and Joel Dodge. + :References + :@HREF{"https://macaulay2.com/", "Macaulay2.com"}@ website, for online documentation, binary distributions, etc. + :Computations in algebraic geometry with Macaulay2, Algorithms and Computations in Mathematics (No. 8), edited by David Eisenbud, Daniel R. Grayson, Michael E. Stillman, and Bernd Sturmfels, Springer-Verlag, 2001, ISBN 3-540-42230-7. + :Computational Algebraic Geometry, London Mathematical Society Student Texts (No. 58), by Hal Schenck, Cambridge University Press, 2003, ISBN 0-521-53650-2. /// -document { - Key => "Start Here", - "Start here if you are new to Macaulay2 or want the basic entry points for - installing it, starting a session, navigating the documentation, and finding help.", - Subnodes => { - TO "setting up Macaulay2", - TO "a first Macaulay2 session", - TO "reading the documentation", - TO "getting help or reporting bugs" - } - } - -document { - Key => "Using Macaulay2", - "This section routes you into the language, package workflow, and the most - common practical topics for daily use.", - PARA{}, - UL { - TO "The Macaulay2 language", - TO "packages", - TO "packages provided with Macaulay2", - TO "debugging", - TO "error handling" - }, - Subnodes => { - TO "The Macaulay2 language", - TO "packages provided with Macaulay2" - } - } - -document { - Key => "Doing Mathematics", - "This section groups the tutorial landing page together with the main - subject-area overview pages for objects and computations.", - Subnodes => { - TO "Tutorials and Examples", - TO "By object", - TO "By computation" - } - } - -document { - Key => "Tutorials and Examples", - "This page gathers the longer guided walkthroughs, teaching materials, and - other tutorial-style entry points.", - Subnodes => { - TO "Tutorials::Tutorials" - } - } - -document { - Key => "By object", - "These overview pages are organized by the kind of mathematical object you - are working with.", - Subnodes => { - TO "rings", - TO "ideals", - TO "matrices", - TO "modules", - TO "morphisms", - TO "Complexes :: Complexes", - TO "Varieties :: Varieties", - TO "Graphs :: Graphs", - TO "Posets :: Posets", - TO "SimplicialComplexes :: SimplicialComplexes", - TO "Polyhedra :: Polyhedra" - } - } - -document { - Key => "By computation", - "These overview pages are organized by the kind of computation you want to - perform.", - Subnodes => { - TO "elementary arithmetic", - TO "linear algebra", - TO "commutative algebra", - TO "homological algebra", - TO "algebraic geometry", - TO "Representation Theory", - TO "combinatorics", - TO "analytic functions" - } - } - -document { - Key => "For Developers", - "This section routes to package-authoring, documentation, debugging, and - internal implementation material without changing the underlying ownership - of those nodes.", - PARA{}, - UL { - TO "creating a package", - TO "writing documentation", - TO "debugging", - TO "error handling", - TO "Macaulay2Doc::Core", - TO "how Macaulay2 finds its files", - TO "the interpreter of Macaulay2", - TO "the engine of Macaulay2", - TO "parallelism in engine computations" - } - } - -document { - Key => "About", - "This section collects acknowledgements, authorship, licensing, version - history, and legacy material related to Macaulay2.", - Subnodes => { - TO "Acknowledgements", - TO "The authors of Macaulay2", - TO "The authors of Macaulay2 packages", - TO "Copyright and license", - TO "changes to Macaulay2, by version", - TO "replacements for commands and scripts from Macaulay" - } - } - end-- restart From 0ad178bab2b0fe0d7b7ff8fd09b79b01abbb4c64 Mon Sep 17 00:00:00 2001 From: klee669 Date: Thu, 21 May 2026 10:58:21 -0400 Subject: [PATCH 64/73] Expand debugging documentation with examples Enrich the Macaulay2 debugging docs (ov_debugging.m2) with a detailed, step-by-step example session: load a demo file, show available symbols (listUserSymbols), display function source (code), trigger the debugger and inspect locals (listLocalSymbols), and demonstrate debugger commands (step, break, end) and the errorDepth setting. Also documents non-interactive error handling using try and trap and includes illustrative REPL output to make debugging workflows clearer for users. --- .../packages/Macaulay2Doc/ov_debugging.m2 | 117 +++++++++++++++++- 1 file changed, 114 insertions(+), 3 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 index 062f6b27a9a..372b96d21c6 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 @@ -2,10 +2,121 @@ document { Key => "debugging", - "Macaulay2 has a debugger.", - UL{ - TO "the debugger", + EM "Debugging ", "means finding out why a computation did not do what you expected.", + PARA{}, + "Macaulay2 has a debugger. In Macaulay2, an error message usually tells you where the computation stopped. ", + "The debugger lets you inspect the values of variables at that moment.", + PARA{}, + "We have a Macaulay2 source file with a pair of functions in it that + we can use for demonstrating the debugger. Let's load it so we can + run the functions in it.", + EXAMPLE PRE /// +i1 : load "Macaulay2Doc/demos/demo1.m2" +///, + "We can see what functions were provided to us with ", TO "listUserSymbols", ".", + EXAMPLE PRE /// +i2 : listUserSymbols + +o2 = symbol class value location of symbol + ------ ----- ----- ------------------ + g FunctionClosure g Macaulay2Doc/demos/demo1.m2:11:0-11:1 +///, + "Let's peek at the code of the function ", TT "g", ".", + EXAMPLE PRE /// +i3 : code g + +o3 = Macaulay2Doc/demos/demo1.m2:11:4-14:9: --source code: + g = y -> ( + c := f(y-1); + d := f(y-2); + c+d) +///, + "We see that the function ", TT "g", " calls a function ", TT "f", ", but ", TT "f", " is not visible to us + (because ", TT "f", " is a local variable). In Emacs' ", EM "Macaulay2 Interaction Mode", ", pressing + return (", TT "RET", " or ", TT "enter", ") after positioning the cursor on the output line displaying the file name and line number + will bring up the source code in a new buffer.", + PARA{"The first few times we use ", TT "g", ", it seems to work."}, + EXAMPLE PRE /// +i4 : g 4 + + 17 +o4 = -- + 6 + +o4 : QQ + +i5 : g 3 + + 7 +o5 = - + 2 + +o5 : QQ +///, + "However, the following attempt results in an error, and the debugger starts up automatically.", + EXAMPLE PRE /// +i6 : g 2 +Macaulay2Doc/demos/demo1.m2:8:11:(3):[3]: error: division by zero +Macaulay2Doc/demos/demo1.m2:8:11:(3): entering debugger (enter 'help' to see commands) +Macaulay2Doc/demos/demo1.m2:8:10-8:13: --source code: + b := 1/x; + +ii7 : +///, + "When the debugger starts, the prompt changes from ", TT "i", " to ", + TT "ii", ". The extra ", TT "i", " means that you are inside another command interpreter: + in this case, the debugger. If you enter the debugger again from inside the debugger, + the prompt may acquire still more ", TT "i", "'s. It is just Macaulay2 saying: you are one level deeper.", + "You may use ", TO "help", ", as instructed, to view the commands available in the debugger. + As suggested by the help display, we can use ", TO "listLocalSymbols", " to list the local symbols and their values.", + EXAMPLE PRE /// +ii7 : listLocalSymbols + +oo7 = symbol class value location of symbol + ------ ----- ----- ------------------ + a String "hi there" Macaulay2Doc/demos/demo1.m2:7:5-7:6 + b Nothing null Macaulay2Doc/demos/demo1.m2:8:5-8:6 + x ZZ 0 Macaulay2Doc/demos/demo1.m2:6:5-6:6 + f FunctionClosure FunctionClosure[Macaulay2Doc/demos/demo1.m2:6:5-9:9] Macaulay2Doc/demos/demo1.m2:6:0-6:1 +///, + "The variable ", TO "errorDepth", " can be used to control how deep inside the code the debugger should be activated. ", + "Inside the debugger, some useful commands are:", + UL { + LI {TO "listLocalSymbols", " -- show local variables and their current values"}, + LI {TO "code", " -- show the source code of a function"}, + LI {TO "step", " -- execute one step or line"}, + LI {TO end, " -- leave the current debugger level"}, + LI {TO "break", " -- leave the debugger entirely and return to top level"} }, + PARA{}, + "For example, after an error, one can try", + EXAMPLE PRE /// +ii8 : break + +i9 : +///, + "The command ", TT "break", " is often the panic button: it gets you out of the debugger + and back to the ordinary top-level prompt.", + PARA{}, + "You can also catch an error without entering the debugger by using ", TO symbol try, + " or ", TO symbol trap, ". This is useful in documentation examples.", + EXAMPLE PRE /// +i9 : try 1/0 else errorMessage + +o9 = errorMessage + +o9 : Symbol + +i10 : (v, err) = trap 1/0 + +o10 = (, division by zero) + +o10 : Sequence + +i11 : toString err + +o11 = division by zero +///, "Here are some other debugging tools.", Subnodes => { TO "the debugger", From 881887a2c79b78874b91d0f1a0d4766e8898998e Mon Sep 17 00:00:00 2001 From: klee669 Date: Thu, 21 May 2026 11:16:26 -0400 Subject: [PATCH 65/73] Update author email in package metadata Replace Kisun Lee's contact email in NumericalCertification.m2 package metadata from kil004@ucsd.edu to kisunl@clemson.edu to reflect the author's updated contact information. --- M2/Macaulay2/packages/NumericalCertification.m2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/M2/Macaulay2/packages/NumericalCertification.m2 b/M2/Macaulay2/packages/NumericalCertification.m2 index 7954a1a8a89..69dcce59f7e 100644 --- a/M2/Macaulay2/packages/NumericalCertification.m2 +++ b/M2/Macaulay2/packages/NumericalCertification.m2 @@ -3,7 +3,7 @@ newPackage( Version => "1.6", Date => "May, 2022", Authors => { - {Name => "Kisun Lee", Email => "kil004@ucsd.edu", HomePage => "https://klee669.github.io"} + {Name => "Kisun Lee", Email => "kisunl@clemson.edu", HomePage => "https://klee669.github.io"} }, Headline => "numerical certification", PackageExports => {"NumericalAlgebraicGeometry"}, From 047243accdf3ff202b50b4bded139ce9d78c9396 Mon Sep 17 00:00:00 2001 From: klee669 Date: Thu, 21 May 2026 11:35:08 -0400 Subject: [PATCH 66/73] Add 'continue' and 'trap' entries to ov_debugging Add TO entries for the debugging commands 'continue' and 'trap' in M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 so they appear in the module's exported TO list. --- M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 | 2 ++ 1 file changed, 2 insertions(+) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 index 2f2c9e3c893..368bf829c65 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 @@ -126,6 +126,7 @@ o11 = division by zero TO "benchmark", TO "Browse::browse", TO "code", + TO "continue", TO "current", TO "currentPosition", TO "lineNumber", -- TODO: rename to currentLineNumber @@ -171,6 +172,7 @@ o11 = division by zero TO "showStructure", TO "showClassStructure", TO "showUserStructure", + TO "trap", TO "userSymbols", TO "listSymbols", TO "lookupCount", From 2ebf720b977212628399a40a009463c2b280faef Mon Sep 17 00:00:00 2001 From: klee669 Date: Thu, 21 May 2026 11:40:07 -0400 Subject: [PATCH 67/73] Fix spacing in debugger doc string Add a trailing space after "deeper." in M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 to ensure correct spacing when the documentation strings are concatenated/printed. This is a minor whitespace-only formatting fix to improve output readability. --- M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 index 368bf829c65..2d122b13115 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 @@ -66,7 +66,7 @@ ii7 : "When the debugger starts, the prompt changes from ", TT "i", " to ", TT "ii", ". The extra ", TT "i", " means that you are inside another command interpreter: in this case, the debugger. If you enter the debugger again from inside the debugger, - the prompt may acquire still more ", TT "i", "'s. It is just Macaulay2 saying: you are one level deeper.", + the prompt may acquire still more ", TT "i", "'s. It is just Macaulay2 saying: you are one level deeper. ", "You may use ", TO "help", ", as instructed, to view the commands available in the debugger. As suggested by the help display, we can use ", TO "listLocalSymbols", " to list the local symbols and their values.", EXAMPLE PRE /// From 86ca2a39d361113781373fbf1c2e22c55b130dd1 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Thu, 21 May 2026 12:44:40 -0400 Subject: [PATCH 68/73] docs: add beginner Shidoku tutorial --- .../packages/Macaulay2Doc/ov_debugging.m2 | 2 - M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 | 4 +- M2/Macaulay2/packages/Tutorials.m2 | 2 + .../packages/Tutorials/tu_beginnerSudoku.m2 | 253 ++++++++++++++++++ 4 files changed, 258 insertions(+), 3 deletions(-) create mode 100644 M2/Macaulay2/packages/Tutorials/tu_beginnerSudoku.m2 diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 index 2d122b13115..20b65c45681 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 @@ -126,7 +126,6 @@ o11 = division by zero TO "benchmark", TO "Browse::browse", TO "code", - TO "continue", TO "current", TO "currentPosition", TO "lineNumber", -- TODO: rename to currentLineNumber @@ -172,7 +171,6 @@ o11 = division by zero TO "showStructure", TO "showClassStructure", TO "showUserStructure", - TO "trap", TO "userSymbols", TO "listSymbols", TO "lookupCount", diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 index 7c9e27f2d0f..a7f1185a4a3 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 @@ -20,7 +20,8 @@ Node Use the expanded sections below to move from learning the system, to working with packages and the language, to guided mathematical examples and subject-area references, to developer and internal documentation. For longer walkthroughs, - start with @TO2("Tutorials::Tutorials", "Tutorials")@. + start with @TO2("Tutorials::Tutorials", "Tutorials")@. For a beginner-friendly + worked example, try @HREF{replace("PKG", "Tutorials", currentLayout#"packagehtml") | "___Beginner_sptutorial_co_sp__Shidoku.html", "Beginner tutorial: Shidoku"}@. Tree :Start Here > "setting up Macaulay2" @@ -35,6 +36,7 @@ Node :Doing Mathematics :Tutorials and Examples * "Tutorials::Tutorials" + :@HREF{replace("PKG", "Tutorials", currentLayout#"packagehtml") | "___Beginner_sptutorial_co_sp__Shidoku.html", "Beginner tutorial: Shidoku"}@ :By Area > "elementary arithmetic" > "linear algebra" diff --git a/M2/Macaulay2/packages/Tutorials.m2 b/M2/Macaulay2/packages/Tutorials.m2 index 4540e66b57b..bf08fb28291 100644 --- a/M2/Macaulay2/packages/Tutorials.m2 +++ b/M2/Macaulay2/packages/Tutorials.m2 @@ -30,6 +30,7 @@ Node :Foundational tutorials > "Tutorial: Modules in Macaulay2" > "Tutorial: Elementary uses of Gröbner bases" + > "Beginner tutorial: Shidoku" > "Teaching Materials" :Geometry tutorials > "Tutorial: Divisors" @@ -65,6 +66,7 @@ document { Key => "Tutorial: Fano varieties", ld "tu_Fano.m2" } +load "./Tutorials/tu_beginnerSudoku.m2" load "./Tutorials/tu_NAG.m2" load "./Macaulay2Doc/M2-Singular-Book.m2" load "./Tutorials/teaching_materials.m2" diff --git a/M2/Macaulay2/packages/Tutorials/tu_beginnerSudoku.m2 b/M2/Macaulay2/packages/Tutorials/tu_beginnerSudoku.m2 new file mode 100644 index 00000000000..a2b5c53e596 --- /dev/null +++ b/M2/Macaulay2/packages/Tutorials/tu_beginnerSudoku.m2 @@ -0,0 +1,253 @@ +doc /// +Node + Key + "Beginner tutorial: Shidoku" + Headline + A first M2 session solving a 4x4 Sudoku + Description + Text + This tutorial is for a new Macaulay2 user who has limited knowledge of commutative algebra. + The goal is to show how Macaulay2 can turn a system of polynomial equations + into useful information. + + The mathematical problem is a 4-by-4 Sudoku puzzle, + sometimes called Shidoku. Instead of solving it by hand, + we encode the rules as polynomial equations and ask Macaulay2 to solve the resulting system. + Text + @BOLD "Starting Macaulay2"@ + + After starting Macaulay2, you should see something like this: + + Pre + i1 : restart + + Text + Macaulay2 labels each input line with @TT "i1, i2"@ and so on. + It labels each output line with @TT "o1, o2"@ and so on. + + Try a few basic commands: + + Example + 2+3 + 2^10 + factor 360 + + Text + While Macaulay2 can be used as a calculator, + its main strength is computation with algebraic objects + like polynomial rings, ideals, modules, maps, complexes, and related structures. + Text + @BOLD "Finding help"@ + + Text + A good first habit is to ask Macaulay2 what it knows. + + Example + help ideal + + Text + If you do not know the exact name of a command, try @TT "apropos"@ or @TT "about"@. + + Example + apropos "Groebner" + + Text + In an interactive session, @TT "viewHelp ideal"@ opens the documentation + page in a browser, and @TT "examples ideal"@ shows examples attached to + that documentation entry. + + Text + @BOLD "The puzzle"@ + + Text + Here is a 4-by-4 Sudoku puzzle we will solve. + The entries are the numbers 1, 2, 3, and 4. + The boxes are 2 rows by 2 columns. + + Pre + +-----+-----+ + | 1 . | . 4 | + | . 4 | 1 . | + +-----+-----+ + | . 1 | 4 . | + | 4 3 | . 1 | + +-----+-----+ + + Text + Here a dot @TT "."@ means that the entry is not yet known. + + Text + @BOLD "The rules"@ + + Text + A completed Shidoku board must satisfy the following conditions: + + @UL { + LI "Each cell contains one of 1, 2, 3, 4.", + LI "Each row contains each number exactly once.", + LI "Each column contains each number exactly once.", + LI "Each 2-by-2 box contains each number exactly once.", + LI "The given clues must be preserved." + }@ + + Text + We will translate these rules into polynomial equations. + + Text + @BOLD "The algebraic idea"@ + + Text + We work over the finite field @TT "ZZ/5"@. Its nonzero elements are + $1,2,3,4$, which are exactly the four symbols allowed in a Shidoku puzzle. + + Text + If @TT "x"@ is a variable representing one cell, then the equation + + Pre + x^4 - 1 = 0 + + Text + forces @TT "x"@ to be one of the nonzero elements of @TT "ZZ/5"@. + + Text + To say that two cells @TT "x"@ and @TT "y"@ contain different symbols, we use + + Pre + (x - y)^4 - 1 = 0 + + Text + This works because every nonzero element @TT "a"@ of @TT "ZZ/5"@ satisfies + $a^4 = 1$. Thus the equation above says that @TT "x-y"@ is nonzero, so + @TT "x"@ and @TT "y"@ must be different. + + Text + In this way, a Shidoku puzzle becomes a system of polynomial equations whose + solutions are exactly the completed boards satisfying all the rules. + + Text + @BOLD "Variables for the cells"@ + + Text + We represent the unknown board by a 4-by-4 matrix of variables + $X = (x_(i,j))$ for $1 \le i,j \le 4$. Here @TT "x_(i,j)"@ is the entry + in row $i$ and column $j$. + + Pre + | x_(1,1) x_(1,2) x_(1,3) x_(1,4) | + | x_(2,1) x_(2,2) x_(2,3) x_(2,4) | + | x_(3,1) x_(3,2) x_(3,3) x_(3,4) | + | x_(4,1) x_(4,2) x_(4,3) x_(4,4) | + + Text + @BOLD "Solving with polynomial constraints"@ + + Text + We begin by creating a polynomial ring over @TT "ZZ/5"@ with one variable + for each cell. The shorthand @TT "x_(1,1)..x_(4,4)"@ creates all 16 variables. + + Example + R = ZZ/5[x_(1,1)..x_(4,4), MonomialOrder => Lex] + R_* + + Text + The list @TT "R_*"@ contains the 16 variables in row-major order: + first the four variables in row 1, then the four in row 2, and so on. + This is enough structure for the tutorial, so we do not actually need to + build a separate matrix @TT "X"@. + + Next we build some helper lists. + + The function @TT "pairwiseDifferent"@ takes a list of cells and writes the + equations forcing all pairs to be different. + Then @TT "rows"@, @TT "cols"@, and @TT "boxes"@ collect the four rows, + four columns, and four 2-by-2 boxes of the puzzle. + The helper @TT "distinctnessRules"@ applies @TT "pairwiseDifferent"@ to a + whole family of lists. + + Example + pairwiseDifferent = L -> toList flatten for i from 0 to #L-1 list + for j from i+1 to #L-1 list + (L#i - L#j)^4 - 1; + rows = apply(0..3, i -> R_*_{4*i..4*i+3}); + cols = apply(0..3, j -> apply(0..3, i -> R_*#(4*i+j))); + boxes = apply({0,2,8,10}, k -> {R_*#k, R_*#(k+1), R_*#(k+4), R_*#(k+5)}); + distinctnessRules = F -> toList flatten apply(F, pairwiseDifferent); + + Text + Now we translate the Shidoku rules into polynomial equations. + + The list @TT "cellRules"@ forces each variable to be one of + @TT "1,2,3,4"@. The lists @TT "rowRules"@, @TT "colRules"@, and + @TT "boxRules"@ enforce the distinctness conditions for rows, columns, + and boxes. + + Example + cellRules = apply(R_*, x -> x^4 - 1); + rowRules = distinctnessRules rows; + colRules = distinctnessRules cols; + boxRules = distinctnessRules boxes; + + Text + Finally we encode the given clues. + + The clue list uses the usual 1-based row and column numbers. Since list + positions in Macaulay2 start at 0, we subtract 1 when converting each + clue into an index of @TT "R_*"@. + + Example + clues = {(1,1,1), (1,4,4), + (2,2,4), (2,3,1), + (3,2,1), (3,3,4), + (4,1,4), (4,2,3), (4,4,1)}; + clueRules = apply(clues, clue -> R_*#(4*(clue#0-1) + (clue#1-1)) - clue#2); + I = ideal(cellRules | rowRules | colRules | boxRules | clueRules); + + Text + The ideal @TT "I"@ now contains all the equations describing the puzzle. + To solve the puzzle, we compute a Gröbner basis for @TT "I"@. + + Example + transpose gens gb I + dim I + degree I + + Text + The Gröbner basis consists of 16 linear equations, one for each cell. + For example, @TT "x_(1,2)-2"@ says that the entry in row 1, column 2 is + 2. The equation @TT "x_(1,3)+2"@ says that @TT "x_(1,3)=-2"@, which means + @TT "x_(1,3)=3"@ in @TT "ZZ/5"@ because @TT "-2 = 3"@ in that field. + + The output @TT "dim I = 0"@ tells us that the ideal defines a + zero-dimensional solution set, so there are only finitely many solutions. + The output @TT "degree I = 1"@ then tells us that there is exactly one + solution, so the Shidoku puzzle has a unique completion. + + Text + @BOLD "Reading the completed board"@ + + Text + Reading the 16 linear equations from the Gröbner basis gives the unique + completed Shidoku board: + + Pre + +-----+-----+ + | 1 2 | 3 4 | + | 3 4 | 1 2 | + +-----+-----+ + | 2 1 | 4 3 | + | 4 3 | 2 1 | + +-----+-----+ + + Text + @BOLD "E. Directions for further exploration"@ + + Text + Possible follow-up directions for the finished tutorial might include: + + @UL { + LI "using a full 9x9 encoding", + LI "comparing symbolic and numerical approaches", + LI "testing uniqueness of a solution", + LI "using the tutorial as a first introduction to ideals and Gröbner bases" + }@ +/// From aa40fc470ada28785e3497126a331a614e14ed8a Mon Sep 17 00:00:00 2001 From: aalmousa Date: Thu, 21 May 2026 12:51:07 -0400 Subject: [PATCH 69/73] docs: fix front page tutorial links --- M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 index a7f1185a4a3..85d1afa3184 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 @@ -20,8 +20,8 @@ Node Use the expanded sections below to move from learning the system, to working with packages and the language, to guided mathematical examples and subject-area references, to developer and internal documentation. For longer walkthroughs, - start with @TO2("Tutorials::Tutorials", "Tutorials")@. For a beginner-friendly - worked example, try @HREF{replace("PKG", "Tutorials", currentLayout#"packagehtml") | "___Beginner_sptutorial_co_sp__Shidoku.html", "Beginner tutorial: Shidoku"}@. + start with @HREF{"common/" | replace("PKG", "Tutorials", currentLayout#"packagehtml") | "index.html", "Tutorials"}@. For a beginner-friendly + worked example, try @HREF{"common/" | replace("PKG", "Tutorials", currentLayout#"packagehtml") | "___Beginner_sptutorial_co_sp__Shidoku.html", "Beginner tutorial: Shidoku"}@. Tree :Start Here > "setting up Macaulay2" @@ -35,8 +35,8 @@ Node > "packages provided with Macaulay2" :Doing Mathematics :Tutorials and Examples - * "Tutorials::Tutorials" - :@HREF{replace("PKG", "Tutorials", currentLayout#"packagehtml") | "___Beginner_sptutorial_co_sp__Shidoku.html", "Beginner tutorial: Shidoku"}@ + :@HREF{"common/" | replace("PKG", "Tutorials", currentLayout#"packagehtml") | "index.html", "Tutorials"}@ + :@HREF{"common/" | replace("PKG", "Tutorials", currentLayout#"packagehtml") | "___Beginner_sptutorial_co_sp__Shidoku.html", "Beginner tutorial: Shidoku"}@ :By Area > "elementary arithmetic" > "linear algebra" From 41b86b781d791d2903e78ac2c0bc13c4b083f6c9 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Thu, 21 May 2026 15:14:47 -0400 Subject: [PATCH 70/73] docs: restore GF map node for package install --- .../Macaulay2Doc/functions/map-doc.m2 | 85 ++++++++++--------- 1 file changed, 45 insertions(+), 40 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 index cf1393f18c8..ad7ded1ff2d 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 @@ -2,46 +2,51 @@ --- author(s): --- notes: -document { - Key => (map, GaloisField, GaloisField), - Headline => "maps of Galois fields", - Usage => "phi = map(F,G)", - Inputs => { - "F" => GaloisField, - "G" => GaloisField - }, - Outputs => { - RingMap => {"the canonical inclusion of ", TT "G", " into a compatible subfield of ", TT "F"} - }, - "GF(p^n) contains GF(p^m) if and only if ", TT "m", " divides ", TT "n", ".", - "The specialized method documented here is ", TT "map(F,G)", ".", - EXAMPLE { - "F2 = GF 2", - "F4 = GF(2^2)", - "F8 = GF(2^3)", - "F16 = GF(2^4)", - "map(F16, F2)", - "map(F16, F4)" - }, - "If no compatible subfield exists, then Macaulay2 signals an error:", - EXAMPLE { - "try map(F16, F8) else \"this map does not exist\"" - }, - "It is also possible to invoke the generic ring-map constructor with an explicit image for a generator of the source field:", - EXAMPLE { - "map(F16, F4, {1})" - }, - "Such a map need not be well-defined:", - EXAMPLE { - "phi = map(F16, F4, {1})", - "isWellDefined phi" - }, - SeeAlso => { - isWellDefined, - GF, - (map,Ring,Ring,List) - } - } +doc /// +Node + Key + (map, GaloisField, GaloisField) + Headline + maps of Galois fields + Usage + phi = map(F,G) + Inputs + F:GaloisField + G:GaloisField + Outputs + phi:RingMap + the canonical inclusion of G into a compatible subfield of F + Description + Text + GF(p^n) contains GF(p^m) if and only if m divides n. + Text + The specialized method documented here is @TT "map(F,G)"@. + Example + F2 = GF 2 + F4 = GF(2^2) + F8 = GF(2^3) + F16 = GF(2^4) + map(F16, F2) + map(F16, F4) + Text + If no compatible subfield exists, then Macaulay2 signals an error: + Example + try map(F16, F8) else "this map does not exist" + Text + It is also possible to invoke the generic ring-map constructor with an + explicit image for a generator of the source field: + Example + map(F16, F4, {1}) + Text + Such a map need not be well-defined: + Example + phi = map(F16, F4, {1}) + isWellDefined phi + SeeAlso + isWellDefined + GF + (map,Ring,Ring,List) +/// undocumented {(map, RingFamily, Thing, Thing),(map, Thing, RingFamily, Thing), (map, RingFamily, Thing), (map, Thing, RingFamily)} From 80963ec05f0257cac2c2bbcf24fe6c95023b8110 Mon Sep 17 00:00:00 2001 From: aalmousa Date: Thu, 21 May 2026 15:39:13 -0400 Subject: [PATCH 71/73] docs: move GF map docs to ConwayPolynomials --- M2/Macaulay2/packages/ConwayPolynomials.m2 | 41 ++++++++++++++++ .../Macaulay2Doc/functions/map-doc.m2 | 48 +------------------ 2 files changed, 42 insertions(+), 47 deletions(-) diff --git a/M2/Macaulay2/packages/ConwayPolynomials.m2 b/M2/Macaulay2/packages/ConwayPolynomials.m2 index 99c86ea995b..1cc0b26c067 100644 --- a/M2/Macaulay2/packages/ConwayPolynomials.m2 +++ b/M2/Macaulay2/packages/ConwayPolynomials.m2 @@ -68,6 +68,47 @@ document { Key => ConwayPolynomials, isWellDefined oo /// } +document { + Key => (map, GaloisField, GaloisField), + Headline => "maps of Conway Galois fields", + Usage => "phi = map(F,G)", + Inputs => { + "F" => GaloisField, + "G" => GaloisField + }, + Outputs => { + RingMap => {"the canonical inclusion of ", TT "G", " into a compatible subfield of ", TT "F"} + }, + "When ", TT "ConwayPolynomials", " is loaded, ", TT "map(F,G)", " constructs the canonical map between compatible Conway-presented finite fields.", + "In this implementation, ", TT "GF(p^n)", " contains ", TT "GF(p^m)", " only when ", TT "m", " divides ", TT "n", ", and both fields must be represented using Conway polynomials.", + EXAMPLE { + "F2 = GF 2", + "F4 = GF(2^2)", + "F8 = GF(2^3)", + "F16 = GF(2^4)", + "map(F16, F2)", + "map(F16, F4)" + }, + "If no compatible subfield exists, then Macaulay2 signals an error:", + EXAMPLE { + "try map(F16, F8) else \"this map does not exist\"" + }, + "It is also possible to invoke the generic ring-map constructor with an explicit image for a generator of the source field:", + EXAMPLE { + "map(F16, F4, {1})" + }, + "Such a map need not be well-defined:", + EXAMPLE { + "phi = map(F16, F4, {1})", + "isWellDefined phi" + }, + SeeAlso => { + ConwayPolynomials, + GF, + isWellDefined, + (map, Ring, Ring, List) + } + } document { Key => {conwayPolynomial, (conwayPolynomial,ZZ,ZZ), (conwayPolynomial,ZZ)}, Headline => "provide a Conway polynomial", diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 index ad7ded1ff2d..84b9c325e09 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 @@ -2,52 +2,6 @@ --- author(s): --- notes: -doc /// -Node - Key - (map, GaloisField, GaloisField) - Headline - maps of Galois fields - Usage - phi = map(F,G) - Inputs - F:GaloisField - G:GaloisField - Outputs - phi:RingMap - the canonical inclusion of G into a compatible subfield of F - Description - Text - GF(p^n) contains GF(p^m) if and only if m divides n. - Text - The specialized method documented here is @TT "map(F,G)"@. - Example - F2 = GF 2 - F4 = GF(2^2) - F8 = GF(2^3) - F16 = GF(2^4) - map(F16, F2) - map(F16, F4) - Text - If no compatible subfield exists, then Macaulay2 signals an error: - Example - try map(F16, F8) else "this map does not exist" - Text - It is also possible to invoke the generic ring-map constructor with an - explicit image for a generator of the source field: - Example - map(F16, F4, {1}) - Text - Such a map need not be well-defined: - Example - phi = map(F16, F4, {1}) - isWellDefined phi - SeeAlso - isWellDefined - GF - (map,Ring,Ring,List) -/// - undocumented {(map, RingFamily, Thing, Thing),(map, Thing, RingFamily, Thing), (map, RingFamily, Thing), (map, Thing, RingFamily)} @@ -89,7 +43,7 @@ document { "Creating a map between modules over different rings", TO (map,Module,Module,RingMap,Matrix), "Creating a map between rings", - TO (map,GaloisField,GaloisField), + TO "ConwayPolynomials :: map(GaloisField,GaloisField)", TO (map,Ring,Ring), TO (map,Ring,Ring,List), TO (map,Ring,Ring,Matrix), From 35c324c6f2f88abfa7bd05353c6102284757384b Mon Sep 17 00:00:00 2001 From: aalmousa Date: Thu, 21 May 2026 15:59:18 -0400 Subject: [PATCH 72/73] Merge pull request #400 from joel-dodge/module-tutorial --- M2/Macaulay2/packages/Tutorials.m2 | 5 +- M2/Macaulay2/packages/Tutorials/tu_modules.m2 | 646 +++++++++++------- 2 files changed, 384 insertions(+), 267 deletions(-) diff --git a/M2/Macaulay2/packages/Tutorials.m2 b/M2/Macaulay2/packages/Tutorials.m2 index bf08fb28291..aeed0837178 100644 --- a/M2/Macaulay2/packages/Tutorials.m2 +++ b/M2/Macaulay2/packages/Tutorials.m2 @@ -42,10 +42,7 @@ Node ld := fn -> tutorial get (currentFileDirectory|"Tutorials/"|fn) -document { - Key => "Tutorial: Modules in Macaulay2", - ld "tu_modules.m2" - } +load "./Tutorials/tu_modules.m2" document { Key => "Tutorial: Elementary uses of Gröbner bases", ld "tu_elementary.m2" diff --git a/M2/Macaulay2/packages/Tutorials/tu_modules.m2 b/M2/Macaulay2/packages/Tutorials/tu_modules.m2 index 5715ea716a3..fc4bbeabad5 100644 --- a/M2/Macaulay2/packages/Tutorials/tu_modules.m2 +++ b/M2/Macaulay2/packages/Tutorials/tu_modules.m2 @@ -1,263 +1,383 @@ --- In this tutorial, we describe how to work with modules in Macaulay2. - ----------------------------------- --- A. Making modules from matrices ----------------------------------- - --- First, let's define a ring. -R = QQ[a..f]; -m = matrix{{a,b,d,e},{b,c,e,f}} - --- Use standard notation for cokernels, images and kernels (coker, cokernel, --- image, ker, kernel). -M = coker m -N = image m -K = kernel m - --- Given a module, one can find its presentation matrix. -presentation M -- this is just the original matrix -presentation N -- this one requires computation - ------------------------------- --- B. Submodules and quotients ------------------------------- --- To define a submodule $IN$ of a module $N$, --- where $I$ is an ideal, use -ideal(a,b)*N -a*N + b*N --- In order to define a submodule of N generated by some --- elements of N, one way is the following. -N0 = image (a**N_{1}|N_{2}-N_{3}) --- To understand what Macaulay2 is doing here, let's break --- this down. {\tt N_{i}} defines a matrix $R^1 \to N$, which maps 1 to --- the i th generator of N. (See Section XX below for more --- information about module homomorphisms). -N_{1} --- One could use {\tt a*N_{1}}, but it turns out that {\tt a ** N_{1}} --- works better: -a ** N_{1} --- Next, remember that the vertical bar concatenates matrices. -a ** N_{1} | N_{2}-N_{3} --- Now take the image of this matrix -N0 = image(a ** N_{1} | N_{2}-N_{3}) --- The main advantage for using ** rather than * is that ** --- preservers homogeneity if possible. -isHomogeneous N0 - --- Quotients are defined using standard mathematical notation. -Nbar = N/N0 --- Notice that this returns a subquotient module. We treat these --- later. - --- Ideals and modules are treated differently in Macaulay2 (and in commutative --- algebra in general). For example, asking for the dimension of an ideal I --- in a ring R gives the dimension of the quotient R/I, but the dimension of the --- module I gives a potentially very different answer. --- Use ideal and module to move between the two. -I = ideal(a^2, a*b, c^2) -J = module I -I == ideal J -codim I -codim J - ------------------------------------ --- C. Syzygies and free resolutions ------------------------------------ - --- Create a free resolution of an ideal (or module) using res. -C = res I --- View the differential -C.dd --- The (graded) betti numbers -betti C --- Use {\tt help betti} for a detailed description --- of what this display means. Basically, it says that I has three --- generators of degree 2, one syzygy of degree 3, 2 syzygies of degree 4, and --- one second syzygy of degree 5. - --- The free resolution of a module that is not a cokernel: -C = res Nbar -betti C -C.dd - --- Here is a problem to experiment with. What different betti diagrams --- are possible with an ideal generated by 3 homogeneous quadric polynomials, --- in a polynomial ring in any number of variables? --- Here is one to get you started. -R = QQ[a..h]; -J = ideal(a*c+b*d,a*e+b*f,a*g+b*h) -betti res J --- After that, try ideals generated by 4 quadrics. - -------------------- --- D. Subquotients -------------------- --- Recall that the module N/N0 above displayed as something called a --- subquotient module. As Macaulay2 often returns such objects, it --- is useful to understand and be able to manipulate them. ---P --- The most common modules are quotients of free modules, or submodules --- of free modules. A useful generalization, which covers both of these --- types, are subquotients: submodules of quotients of free modules. ---P --- A subquotient module is determined by two matrices $f : R^m \to R^n$ --- and $g : R^p \to R^n$. The subquotient module with generators f, relations --- g is by definition the module M = (image f) + (image g) / (image g). --- Thus, if f is the identity map, M = coker g, and if g = 0, then M = image f. -use ring M -M -N = a*M -M/N --- The two matrices f and g mentioned above are recovered using --- the routines: generators, relations. -generators N -relations N - --- It is often necessary to find a presentation matrix for such modules. -presentation N - --- Often the given representation of a module is not very efficient. --- Use trim to keep the module as a subquotient of the same ambient free module, --- but change the generators and relations to be minimal, or in the nonlocal or --- non-graded case, at least more efficient. -trim N --- Use minimalPresentation to also allow the ambient free module to be improved. --- This returns a quotient of a free module, but in the future might not do that. -minimalPresentation N --- prune is a synonym for minimalPresentation N -prune N - --- Given a subquotient module N, there are several useful modules associated --- to N. --- The free module of which N is a subquotient is obtained using ambient. -ambient N --- This is the same as the target of either the generator or relation matrix. -ambient N == target generators N -ambient N == target relations N - --- N is a submodule of a quotient module $R^n/image(g)$. The routine super --- returns this quotient module -super N --- This is the same as -super N == coker relations N - --- The cover of N is basically the source of the matrix of generators. -cover N -cover N == source generators N - ------------------------------------ --- E. Homomorphisms between modules ------------------------------------ --- A homomorphism $f : M \to N$ is represented as a matrix from the --- generators of M to the generators of N. -A = QQ[x,y]/(y^2-x^3) -M = module ideal(x,y) - --- One homomorphism $F : M \to A$ is $x \mapsto y, y \mapsto x^2$ (multiplication by y/x) --- We write this as: -F = map(A^1,M,matrix{{y,x^2}}) --- Notice that as is usual in Macaulay2, the target comes before the source. -source F == M -target F == A^1 -matrix F - --- The image of F lies in the submodule M of $A^1$. To obtain the map --- $M \to M$, we use //. But first we need the inclusion map --- of M into $A^1$: --- Later we explain this, but for now, we just write down this map: -inducedMap(A^1,M) --- Now we use // to lift $F : M \to A$ along $M \to A^1$, to get $M \to M$: -G = F // inducedMap(A^1,M) -source G -target G --- G is now a map from $M \to M$. -isWellDefined G - ---------------------------------------------- --- F. Canonical maps associated with modules ---------------------------------------------- --- Let's start with a module M, and a submodule N. -R = QQ[x,y,z,w] -M = ideal(x,y,z)/ideal(x^2,y^2,z*w) -N = z*M -M/N - --- If two modules have the same ambient free module, then there is --- often a canonical map between them. --- Some modules having the same ambient free module: -M -ambient M -N = z*M -ambient(M/N) -super M -super N -image generators M --- --- If two modules M and N have the same ambient module $R^n$, then inducedMap(M,N) --- makes the canonical map $N \to M$ between them, if one exists. If a map --- doesn't exist, the returned map might not be a homomorphism. -inducedMap(M,M) == id_M -inducedMap(super M,M) == map(super id_M) -- the map $(P+Q)/Q \to R^n/Q$, where $M=(P+Q)/Q$. -inducedMap(super M,ambient M) -- the quotient map $R^n \to R^n/Q$ -inducedMap(M,N) -- the inclusion map --- The projection map $M \to M/N$ -inducedMap(M/N,M) -- the projection map --- The projection map $N \to M/N$, which is the zero map -inducedMap(M/N,N) -- the zero map --- Not all such maps can be defined. The functions 'inducedMap' normally checks that the --- result is a well-defined homomorphism. The option 'Verify' controls that behavior. -inducedMap(M,M/N,Verify => false) -inducedMap(M/N,x*M) -inducedMap(M/N,M) * inducedMap(M,x*M) == inducedMap(M/N,x*M) - --- --- --- Before doing interesting homomorphisms, let's see how to write down --- some canonical homomorphisms associated to M. - - --- exercises: --- 1. isomorphism theorems. Given submodules M and N of a module P, --- (a) find $(M+N)/M$ --- (b) find $N/(M \cap N)$ --- (c) find in Macaulay2, an isomorphism between them. --- --- 2. Given a homomorphism $M \to A$. Suppose that --- the image lies in M (M is a submodule of $A^1$). --- Find the map $M \to M$. - - ---------------------------- --- G. Homomorphisms and Hom ---------------------------- -A = QQ[x,y,Degrees=>{2,3}]/(y^2-x^3) -M = module ideal(x,y) -H = Hom(M,M) --- The elements of H correspond to homomorphisms $M \to A$. --- The homomorphism associated to elements of H may be obtained --- using the routine homomorphism. -F = homomorphism(H_{0}) -G = homomorphism(H_{1}) -source F == M -target F == M -ker F -coker F -m = matrix{{x,y},{y,x}} -Hom(m,A^2) -Hom(A^2,m) - ---------------------- --- H. Tensor products ---------------------- --- In Macaulay2, ** denotes the tensor product operator. -m ** m -(coker m) ** (coker m) --- Notice that tensor products of matrices and of modules are --- very different. -M = coker m -M2 = prune(M ** M) -A = QQ[a,b,c] -A ** A --- Macaulay2 renames variables whose names collide. --- Alternatively, one can give the variables as an option to tensor. -tensor(A,A,Variables=>{a,b,c,d,e,f}) +doc /// +Key + "Tutorial: Modules in Macaulay2" +Headline + working with modules +Description + + Text + @BOLD "A. making modules from matrices"@ + Text + To define a module we must first define a ring. + Example + R = QQ[a..f]; + m = matrix{{a,b,d,e},{b,c,e,f}} + Text + Perhaps the simplest examples are the free modules. + Example + R^1 + R^2 + R^3 + Text + Given a matrix $m$ over $R$, there are a number of natural modules associated to $m$. + Example + m = matrix{{a,b,d,e},{b,c,e,f}} + M = coker m + N = image m + K = kernel m + Text + Macaulay2 can easily find a presentation of any of these modules. + Example + presentation M -- this is just the original matrix + presentation N -- this requires computation + + + Text + @BOLD "B. Submodules and quotients"@ + Text + Macaulay2 knows how to multiply a module $M$ by an ideal $I$ to form $IM$. + Example + I = ideal(a, b) + N + I * N + Text + You can also multiply a module by an elements of it's ring and you can add submodules together. + Example + a * N + b * N + Text + You can access generators of module in many convenient forms. Macaulay2 + is happy to view elements of a module as either vectors or as + homomorphisms $R^1 \rightarrow N$ depending on how you are using them. + Example + N_* -- full list of generators + N_0 -- single generator by index as a vector + N_{0} -- single generator by index as a matrix + N_{0..numgens N - 1} -- full matrix of generators + Text + Using this we can easily define specific submodules of a module by giving generators. + Example + g = a ** N_{1} -- see note below on use of ** + g' = N_{2} - N_{3} + G = g | g' + N0 = image G + Text + Multiplication of matrices by a ring element and tensor product with a + ring element have subtle differences under the hood. See @TO "Matrix ** RingElement"@. In this case, we have + opted for tensoring since some degree information is preserved and + the result is homogeneous. + Example + isHomogeneous N0 + Text + We can define quotient modules using standard mathematical notation. + Example + Nbar = N/N0 + Text + Notice that the result is a "subquotient" module, we will dig into the + details of subquotients and how Macaulay2 represents modules in section D below. + See @TO "subquotient modules"@ for more details. + Text + Ideals and modules are treated differently in Macaulay2 (and in commutative + algebra in general). For example, asking for the dimension of an ideal $I$ + in a ring $R$ gives the dimension of the quotient $R/I$, but the dimension of + $I$ as a module gives a potentially very different answer. + Use ideal and module to move between the two. + Example + I = ideal(a^2, a*b, c^2) + J = module I + I == ideal J + codim I + codim J + Text + You cannot convert a module to an ideal unless it is a submodule of a rank-1 free module. + Example + M = I/I^2 + try ideal M else "error: expected a submodule of a free module of rank 1" + + Text + @BOLD "C. Syzygies and free resolutions"@ + + Text + Create a free resolution of an ideal (or module) using res. + Example + C = res I + Text + View the differential + Example + C.dd + Text + The (graded) betti numbers + Example + betti C + Text + Use {\tt help betti} for a detailed description + of what this display means. Basically, it says that I has three + generators of degree 2, one syzygy of degree 3, 2 syzygies of degree 4, and + one second syzygy of degree 5. + + Text + The free resolution of a module that is not a cokernel: + Example + C = res Nbar + betti C + C.dd + + Text + Here is a problem to experiment with. What different betti diagrams + are possible with an ideal generated by 3 homogeneous quadric polynomials, + in a polynomial ring in any number of variables? + Here is one to get you started. + Example + R = QQ[a..h]; + J = ideal(a*c+b*d,a*e+b*f,a*g+b*h) + betti res J + Text + After that, try ideals generated by 4 quadrics. + + + Text + @BOLD "D. Subquotients"@ + Text + Recall that the module N/N0 above displayed as something called a + subquotient module. As Macaulay2 often returns such objects, it + is useful to understand and be able to manipulate them. + + The most common modules are quotients of free modules, or submodules + of free modules. A useful generalization, which covers both of these + types, are subquotients: submodules of quotients of free modules. + + A subquotient module is determined by two matrices $f : R^m \to R^n$ + and $g : R^p \to R^n$. The subquotient module with generators f, relations + g is by definition the module $M = (\text{image } f + \text{image } g) / (\text{image } g)$. + Thus, if $f$ is the identity map, $M = \text{coker } g$, and if $g = 0$, then $M = \text{image } f$. + Example + use ring M + M + N = a*M + M/N + Text + The two matrices f and g mentioned above are recovered using the routines: @TO generators@, @TO relations@. + Example + generators N + relations N + + Text + It is often necessary to find a @TO presentation@ matrix for such modules. + Example + presentation N + + Text + Often the given representation of a module is not very efficient. + Use trim to keep the module as a subquotient of the same ambient free module, + but change the generators and relations to be minimal, or in the nonlocal or + non-graded case, at least more efficient. + Example + trim N + Text + Use @TO minimalPresentation@ to also allow the ambient free module to be improved. + This returns a quotient of a free module, but in the future might not do that. + Example + minimalPresentation N + Text + prune is a synonym for minimalPresentation N + Example + prune N + + Text + Given a subquotient module N, there are several useful modules associated + to N. + The free module of which N is a subquotient is obtained using @TO ambient@. + Example + ambient N + Text + This is the same as the target of either the generator or relation matrix. + Example + ambient N == target generators N + ambient N == target relations N + + Text + N is a submodule of a quotient module $R^n/image(g)$. The routine @TO super@ + returns this quotient module + Example + super N + Text + This is the same as + Example + super N == coker relations N + + Text + The @TO cover@ of N is basically the source of the matrix of generators. + Example + cover N + cover N == source generators N + + Text + @BOLD "E. Homomorphisms between modules"@ + Text + A homomorphism $f : M \to N$ is represented as a matrix from the + generators of M to the generators of N. + Example + A = QQ[x,y]/(y^2-x^3) + M = module ideal(x,y) + + Text + One homomorphism $F : M \to A$ is $x \mapsto y, y \mapsto x^2$ (multiplication by y/x) + We write this as: + Example + F = map(A^1,M,matrix{{y,x^2}}) + Text + Notice that as is usual in Macaulay2, the target comes before the source. + Example + source F == M + target F == A^1 + matrix F + + Text + The image of F lies in the submodule M of $A^1$. To obtain the map + $M \to M$, we use @TO "//"@". But first we need the inclusion map + of M into $A^1$: + Later we explain this, but for now, we just write down this map: + Example + inducedMap(A^1,M) + Text + Now we use // to lift $F : M \to A$ along $M \to A^1$, to get $M \to M$: + Example + G = F // inducedMap(A^1,M) + source G + target G + Text + G is now a map from $M \to M$. + Example + isWellDefined G + + Text + @BOLD "F. Canonical maps associated with modules"@ + Text + Let's start with a module M, and a submodule N. + Example + R = QQ[x,y,z,w] + M = ideal(x,y,z)/ideal(x^2,y^2,z*w) + N = z*M + M/N + + Text + If two modules have the same ambient free module, then there is often a + canonical map between them. Some modules having the same ambient free + module: + Example + M + ambient M + N = z*M + ambient(M/N) + super M + super N + image generators M + Text + If two modules M and N have the same ambient module $R^n$, then @TO + inducedMap@ can be used to produce the canonical map between them if one + exists. If a map doesn't exist, the returned map might not be a + homomorphism. + Example + inducedMap(M, M) == id_M + inducedMap(super M, M) == map(super id_M) -- the map $(P+Q)/Q \to R^n/Q$, where $M=(P+Q)/Q$. + inducedMap(super M, ambient M) -- the quotient map $R^n \to R^n/Q$ + inducedMap(M, N) -- the inclusion map + Text + The projection map $M \to M/N$ + Example + inducedMap(M/N, M) -- the projection map + Text + The projection map $N \to M/N$, which is the zero map + Example + inducedMap(M/N, N) -- the zero map + Text + Not all such maps can be defined. The function @TT "inducedMap"@ normally checks that the + result is a well-defined homomorphism. The boolean option @TT "Verify"@ + lets you specify whether you want this to be checked. + Example + inducedMap(M, M/N, Verify => false) + inducedMap(M/N, x*M) + inducedMap(M/N, M) * inducedMap(M, x*M) == inducedMap(M/N, x*M) + + Text + Before doing interesting homomorphisms, let's see how to write down + some canonical homomorphisms associated to M. + + Text + @BOLD "Some exercises"@: + + 1. isomorphism theorems. Given submodules M and N of a module P: + + (a) find $(M+N)/M$ + + (b) find $N/(M \cap N)$ + + (c) find in Macaulay2, an isomorphism between them. + + 2. Given a homomorphism $M \to A$. Suppose that the image lies in M (M + is a submodule of $A^1$). Find the map $M \to M$. + + Text + @BOLD "G. Homomorphisms and Hom"@ + Text + If $R$ is a commutative ring, then the collection of morphisms between + two $R$-modules inherits an $R$-module structure. Macaulay2 will + construct this for you as an abstract module. + Example + A = QQ[x, y, Degrees => {2, 3}] / (y^2 - x^3) + M = module ideal(x,y) + H = Hom(M,M) + Text + In order to find the homomorphism associated to an element of a $\text{Hom}$ module as a matrix, use the @TO + homomorphism@ function. + Example + F = homomorphism(H_0) + source F == M + target F == M + Text + Of course, you can then form the modules associated to this matrix. + Example + ker F + coker F + Text + $\text{Hom}$ is a bi-functor. If $m$ is a matrix representing a map $B + \rightarrow C$, then for any module $M$ we have $\text{Hom}(m, M): \text{Hom}(C, M) + \rightarrow \text{Hom}(B, M)$ and $\text{Hom}(M, m): \text{Hom}(M, B) + \rightarrow \text{Hom}(M, C)$ + Example + m = matrix{{x,y},{y,x}} + B = source m; + C = target m; + + source Hom(m, M) == Hom(C, M) + target Hom(m, M) == Hom(B, M) + source Hom(M, m) == Hom(M, B) + target Hom(M, m) == Hom(M, C) + + Text + You can go from a matrix to the element of $\text{Hom}$ that represents it using @TO "homomorphism'"@. + Example + m = matrix {{x, 0}, {y, x^2 + x}} + homomorphism' m + + Text + @BOLD "H. Tensor products"@ + Text + In Macaulay2, @TO "**"@ denotes the tensor product operator. It is an + alias for @TO tensor@. Here we see tensor product of matrices and tensor product of modules + Example + m ** m + (coker m) ** (coker m) + coker(m ** m) + Text + Note that tensor products of matrices and of modules are very different. + Text + You can also form tensor products of rings. + Example + A = QQ[a,b,c] + A ** A + Text + Macaulay2 will automatically rename variables when there are name collisions. + Alternatively, for more control, you can give explicit variables as an option using the tensor form. + Example + tensor(A,A,Variables=>{a,b,c,d,e,f}) +/// \ No newline at end of file From 6cf4531909f4839807c309d378bef9f69b39af9d Mon Sep 17 00:00:00 2001 From: aalmousa Date: Thu, 21 May 2026 15:59:22 -0400 Subject: [PATCH 73/73] Merge pull request #401 from joel-dodge/subquotient-docs --- .../packages/Macaulay2Doc/ov_modules.m2 | 231 ++++++++++-------- 1 file changed, 126 insertions(+), 105 deletions(-) diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 index 9dacabcb8e4..c9ff9063f21 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 @@ -282,111 +282,132 @@ document { }, } -document { - Key => "subquotient modules", - Headline => "the way Macaulay2 represents modules", - "Not all modules arise naturally as submodules or quotients of free modules. As an example, - consider the module ", TEX "$M = I/I^2$", " in the example below.", - EXAMPLE { - "R = QQ[x,y,z];", - "I = ideal(x*y,x*z,y*z)", - "M = I/I^2" - }, - TEX "Macaulay2 represents each module (at least conceptually) as a subquotient module, that is, a submodule of - a quotient of an ambient free module. A subquotient module is determined by two - matrices $f : R^m \\rightarrow{} R^n$ and $g : R^p \\rightarrow{} R^n$. - The {\\em subquotient module} with generators $f$ and relations $g$ is by definition the module - $M = ((image f) + (image g))/(image g)$.", - PARA{}, - TEX "If $f$ is the identity map, $M = coker g$, and if $g = 0$, then $M = image f$. - The class of subquotient modules is the smallest class containing free modules, which is closed - under taking submodules and quotients.", - PARA{}, - "One may create a subquotient module directly from matrices f and g having the same target free module.", - EXAMPLE { - "f = matrix{{x,y}}", - "g = matrix{{x^2,x*y,y^2,z^4}}", - "M = subquotient(f,g)" - }, - "The same module can be constructed in the following manner.", - EXAMPLE { - "N = (image f)/(image g)", - "N1 = (image f + image g)/(image g)", - "M === N" - }, - "Notice that Macaulay2 allows one to write (image f)/(image g), even though - mathematically this really means: (image f + image g)/(image g). There is an important - difference however. Modules in Macaulay2 always come with an ordered set of generators, - and N1 has 4 more generators (all zero in the module!) than N. The - modules M and N though are identical.", - PARA{}, - "The two matrices f and g mentioned above are recovered using the - routines ", TO (generators,Module), " and ", TO (relations,Module), ".", - EXAMPLE { - "generators M", - "relations M" - }, - PARA{}, - "Submodules and quotients of free modules work as one would imagine.", - EXAMPLE { - "N2 = R*M_0 + I*M", - "M/N2", - "prune(M/N2)" - }, - PARA{}, - "Given a subquotient module M, there are several useful modules associated to M.", - "The free module of which M is a subquotient is obtained using ", TO (ambient,Module), ".", - EXAMPLE { - "ambient M" - }, - "This is the same as the common target of the matrices of generators and - relations.", - EXAMPLE { - "ambient M === target relations M", - "ambient M === target generators M" - }, - "M is a submodule of the module R^n/(image g). The routine ", TO (super,Module), - " returns this quotient module.", - EXAMPLE { - "super M" - }, - "This may be obtained directly as the cokernel of the matrix of relations.", - EXAMPLE { - "super M === cokernel relations M" - }, - "Often the given representation of a module is not very efficient. - Use ", TO (trim,Module), " to keep the module as a subquotient of the - same ambient free module, - but change the generators and relations to be minimal, or in the nonlocal or - non-graded case, at least more efficient.", - EXAMPLE { - "M + M", - "trim (M+M)" - }, - "Use ", TO (minimalPresentation,Module), " to also allow the ambient free - module to be improved. This currently returns a quotient of a free - module, but in the future it might not.", - EXAMPLE { - "minimalPresentation M" - }, - TT "prune", " is a synonym for ", TT "minimalPresentation", ".", - EXAMPLE { - "prune M" - }, - "For maps between modules, including between subquotient modules, see ", - TO "module homomorphisms", ".", - SeeAlso => { - (ambient,Module), - (super,Module), - (generators,Module), - (relations,Module), - (trim,Module), - (minimalPresentation,Module) - }, - Subnodes => { - TO subquotient, - }, - } +doc /// + Key + "subquotient modules" + Headline + the way Macaulay2 represents modules + Description + Text + Not all modules arise naturally as submodules or quotients of free modules. As an example, + consider the module $M = I/I^2$ in the example below. + Example + R = QQ[x, y, z]; + I = ideal(x*y, x*z, y*z) + M = I/I^2 + Text + In Macaulay2 each module is represented at - least conceptually - + as a subquotient module. A subquotient module is a @BOLD + "submodule"@ of a @BOLD "quotient"@ of a free module. A + subquotient module can be specified by giving two matrices $f : + R^m \rightarrow{} R^n$ and $g : R^p \rightarrow{} R^n$. In this + case, the {\em subquotient module} with generators $f$ and + relations $g$ is by definition the module $M = (\text{image } f + + \text{image } g)/\text{image } g$. + + One may create a subquotient module directly from matrices f and + g having the same target free module. + Example + f = matrix{{x, y}} + g = matrix{{x^2, x*y, y^2, z^4}} + assert(target f == target g) + M = subquotient(f, g) + Text + If $f$ is the identity map, then $M = \text{coker } g$, and if $g = 0$, then $M = \text{image } f$. + In fact, the class of subquotient modules is the smallest class containing free modules, which is closed + under taking submodules and quotients. + Example + F = target f + prune subquotient(id_F, g) -- this is only isomorphic to coker g + subquotient(f, 0 * id_F) + Text + We can recover $f$ and $g$ from $M$ with the routines @TO + (generators,Module)@ and @TO (relations,Module)@. + Example + generators M + relations M + Text + The same module can be constructed directly via + Example + N = (image f)/(image g) + Text + Notice that Macaulay2 allows one to write @TT"(image f)/(image + g)"@. Mathematically this is the same as @TT "(image f + image + g)/image g"@ but there is a subtle difference in Macaulay2. + Example + N' = (image f + image g)/(image g) + Text + Modules in Macaulay2 always come with an ordered set of + generators, and $N'$ has 4 more generators than $N$. This is enough to make $N'$ and $N$ different + modules even though they are isomorphic. The + fact that their difference consists of a collection of generators + that are all zero in $N$ doesn't matter! + Example + assert(N =!= N') + Text + The modules M and N are identical. + Example + assert(M === N) + Text + You can form submodules and quotients of subquotients as you would expect. + Example + N'' = R*M_0 + I*M + M/N'' + prune(M/N'') + Text + @BOLD "Some modules associated to a subquotient"@ + Text + Given a subquotient module M, there are several useful modules associated to M. + The free module of which M is a subquotient is obtained using @TO (ambient, Module)@. + Example + ambient M + Text + This is the same as the common target of the matrices of generators and relations. + Example + ambient M === target relations M + ambient M === target generators M + Text + M is a submodule of the module $R^n/(\text{image } g)$. The routine TO (super,Module) returns this quotient module. + Example + super M + Text + This can also be obtained directly as the cokernel of the matrix of relations. + Example + super M === cokernel relations M + Text + Often the given representation of a module has superfluous + generators or relations or is otherwise more complicated than you + would like. + + You can use @TO (trim,Module)@ to change the generators and + relations to be minimal (in the non-local or non-graded case, + they may be only improved but not minimal) while keeping the + module as a subquotient of the same ambient free module. + Example + M + M + trim (M + M) + Text + Use @TO (minimalPresentation,Module)@ to also allow the ambient free + module to be improved. This currently returns a quotient of a free + module, but in the future it might not. + Example + minimalPresentation M + Text + You can use @TT "prune"@ as a synonym for @TT "minimalPresentation"@. + Example + prune M + Text + For maps between modules, including between subquotient modules, see @TO "module homomorphisms"@. + SeeAlso + (ambient, Module) + (super, Module) + (generators, Module) + (relations, Module) + (trim, Module) + (minimalPresentation, Module) + Subnodes + @TO "subquotient"@ +/// document { Key => "module homomorphisms",