diff --git a/.github/ISSUE_TEMPLATE/documentation-task.yml b/.github/ISSUE_TEMPLATE/documentation-task.yml new file mode 100644 index 00000000000..64735a31530 --- /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: + - documentation +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/.github/pull_request_template.md b/.github/pull_request_template.md index 3ad99033e21..05ae381ce8c 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 `Macaulay2/M2` or `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 + +- Keep the scope focused. Split unrelated documentation work into separate PRs. +- See `README.md` and the Macaulay2 wiki for the current contribution + workflow. 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/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. 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/=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/AInfinity.m2 b/M2/Macaulay2/packages/AInfinity.m2 index ca8cb2de325..be6e73d93b4 100644 --- a/M2/Macaulay2/packages/AInfinity.m2 +++ b/M2/Macaulay2/packages/AInfinity.m2 @@ -20,9 +20,13 @@ export { "picture", "displayBlocks", "extractBlocks", + + "mapComponents", +-* "hasMinimalMult", "isGolodAInf", "burkeDifferential", +*- --symbols "Check", "ShowRanks" @@ -591,6 +595,61 @@ mapComponents(HashTable, HashTable, ZZ) := List =>(mA,mG,len) ->( for t from 1 to len list burkeDifferentialList(mA,mG,t) ) +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 @@ -1947,13 +2021,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! @@ -1978,6 +2063,56 @@ R = S/gor 3 elapsedTime burkeResolution(coker vars R, 7) elapsedTime res(coker vars R, LengthLimit => 7) picture burkeResolution(coker vars R, 5) + + +----------- +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 +-* picture(burkeResolution(coker vars R, 5),"ShowRanks"=>true) mR = aInfinity R @@ -1993,3 +2128,4 @@ I = ideal(u^3, x*y^2, (x+y)*z^2, x^2*u+z*u^2, y^2*u+x*z*u, y^2*z+y*z^2) J = trim (I + (ideal vars S)^6) hasMinimalMult(quotient J, 2) isGolodAInf quotient J +*- 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/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/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/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" - 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/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/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..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 @@ -78,10 +76,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 @@ -185,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 @@ -196,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}$ @@ -213,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/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/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), diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 index 11a850045f1..90a88eb6ad5 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/kernel-doc.m2 @@ -1,79 +1,144 @@ --- -*- coding: utf-8 -*- ---- status: TODO ---- author(s): ---- notes: - -undocumented { - [kernel, DegreeLimit], - [kernel, Strategy], -} - doc /// 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 { - 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 matrix", - Usage => "kernel f", - 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.", - EXAMPLE lines /// - R = ZZ/32003[vars(0..10)] - M = genericSkewMatrix(R,a,5) - ker M - ///, - SeeAlso => {syz, - -- Mike wanted this: "kernel, cokernel and image of a map of modules", - genericSkewMatrix} - } - 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. +Caveat + Used only for computing the kernel of a @TO RingMap@. +/// + + +doc /// +Key + [kernel, DegreeLimit] +Headline + stop after finding enough elements of a subring +Description + Text + @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@. +/// + + +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"@. +Caveat + Used only for computing the kernel of a @TO RingMap@. +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 175dc570d33..84b9c325e09 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/map-doc.m2 @@ -2,11 +2,6 @@ --- author(s): --- notes: --* --- TODO -(map,GaloisField,GaloisField) -*- - undocumented {(map, RingFamily, Thing, Thing),(map, Thing, RingFamily, Thing), (map, RingFamily, Thing), (map, Thing, RingFamily)} @@ -45,9 +40,10 @@ 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 "ConwayPolynomials :: map(GaloisField,GaloisField)", TO (map,Ring,Ring), TO (map,Ring,Ring,List), TO (map,Ring,Ring,Matrix), diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/tensor-doc.m2 index c30c056a629..be71b6f811b 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); 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') + SeeAlso + "OldChainComplexes :: ChainComplex" + Module +/// diff --git a/M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2 b/M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2 index d1e90017113..14c68c4fb4c 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/functions/wedgeProduct-doc.m2 @@ -1,23 +1,28 @@ ---- status: TODO ---- 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 diff --git a/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 b/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 index 285dbdb7320..330664179dd 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/loads.m2 @@ -65,32 +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. Math 634 Fall 2005", - ld "tu_elementary1.m2" - } -document { - Key => "Tutorial: Fano varieties", - ld "tu_Fano.m2" - } diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_analytic_functions.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_analytic_functions.m2 index 3fb8fe12fbb..33f911d9fad 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_analytic_functions.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_analytic_functions.m2 @@ -17,6 +17,27 @@ 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. + 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" + "FormalGroupLaws :: FormalGroupLaws" + "EllipticCurves :: EllipticCurves" + "NumericalAlgebraicGeometry :: NumericalAlgebraicGeometry" Subnodes Constant -- the class of constants :Special functions @@ -77,6 +98,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_debugging.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 index 8d46c297d8c..20b65c45681 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", diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 index b92cbef9104..5ac23338363 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_examples.m2 @@ -2,146 +2,350 @@ doc /// Node Key "elementary arithmetic" + Description + Text + Elementary arithmetic in Macaulay2 includes integer and modular arithmetic, + factorization, gcd/lcm computations, and finite-field calculations. + 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" + "Cyclotomic :: Cyclotomic" + "LLLBases :: LLLBases" + "EllipticCurves :: EllipticCurves" + "Units :: Units" Subnodes + gcd + lcm + factor + gcdCoefficients + powermod mod + quotient + quotient' + quotientRemainder + quotientRemainder' + remainder + remainder' + pseudoRemainder plus minus - difference times power - powermod - (sqrt, ZZ, ZZ) - lcm - gcd - gcdCoefficients - factor + (sqrt,ZZ,ZZ) + random + +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. + 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 + id + inverse + rank Node Key "commutative algebra" + Description + Text + Commutative algebra in Macaulay2 centers on ideals, modules, Groebner bases, + syzygies, Hilbert invariants, elimination, and resolution techniques. + 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 + "packages provided with Macaulay2" + "IntegralClosure :: IntegralClosure" + "PrimaryDecomposition :: PrimaryDecomposition" + "ReesAlgebra :: ReesAlgebra" + "MinimalPrimes :: MinimalPrimes" + "Depth :: Depth" + "Elimination :: Elimination" + "Saturation :: Saturation" + "Regularity :: Regularity" + "LocalRings :: LocalRings" Subnodes + codim + dim + depth + height "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 + minimize monomialCurveIdeal + numgens + pdim + trim + isAffineRing isBorel isCommutative - isAffineRing 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. + 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" + "OldChainComplexes :: OldChainComplexes" + "ChainComplexExtras :: ChainComplexExtras" + "DGAlgebras :: DGAlgebras" + "TorAlgebra :: TorAlgebra" + "SchurFunctors :: SchurFunctors" + "TensorComplexes :: TensorComplexes" + "MCMApproximations :: MCMApproximations" Subnodes - kernel cokernel - image - coimage - preimage - pullback - pushout + complete + directSum + eagonNorthcott + Ext extend - "OldChainComplexes :: nullhomotopy" + HH + image isExact isInjective - isSurjective isIsomorphism - inverse + isSurjective + koszul + presentation + prune ScriptedFunctor - id - HH + syz + tensor Tor - Ext 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. + 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 + "packages provided with Macaulay2" + "Varieties :: Varieties" + "Schubert2 :: Schubert2" + "NormalToricVarieties :: NormalToricVarieties" + "CharacteristicClasses :: CharacteristicClasses" + "HyperplaneArrangements :: HyperplaneArrangements" + "RationalPoints :: RationalPoints" + "ToricVectorBundles :: ToricVectorBundles" Subnodes - singularLocus - Grassmannian - Schubert + chi + euler + eulers Fano + genera + genus + Grassmannian isNormal isSmooth isVeryAmple + preimage + pullback + pushout randomKRationalPoint - chi - euler - eulers - genus - genera + Schubert + singularLocus + +Node + Key + "Representation Theory" + Description + Text + Representation theory in Macaulay2 currently centers on symmetric + functions, Schur and Weyl functors, Lie algebras and their + representations, highest-weight methods, group actions, invariant + theory, and related character computations. + 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. + SeeAlso + "packages provided with Macaulay2" + "SchurRings :: SchurRings" + "SchurFunctors :: SchurFunctors" + "PieriMaps::PieriMaps" + "WeylGroups :: WeylGroups" + "LieAlgebraRepresentations :: LieAlgebraRepresentations" + "GradedLieAlgebras :: GradedLieAlgebras" + "HighestWeights :: HighestWeights" + "InvariantRing :: InvariantRing" + "BettiCharacters :: BettiCharacters" Node Key "combinatorics" + Description + Text + Combinatorics in Macaulay2 spans graphs, posets, simplicial complexes, + polyhedra, lattice polytopes, and combinatorial commutative algebra. + 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" + "Posets :: Posets" + "EdgeIdeals :: EdgeIdeals" + "SimplicialComplexes :: SimplicialComplexes" + "Polyhedra :: Polyhedra" + "LatticePolytopes :: LatticePolytopes" + "Nauty :: Nauty" + "FourTiTwo :: FourTiTwo" Subnodes binomial compositions + cone + directProduct inversePermutation + multidegree + normalCone partitions - random - shuffle - Set rays - cone - normalCone - multidegree + Set /// - -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.", - PARA{}, - "Macaulay2 examples corresponding to the Singular examples in the - book by Greuel-Pfister may also be found here.", - Subnodes => { - TO "Elementary uses of Groebner bases I. Math 634 Fall 2005", - TO "M2SingularBook" - } - } diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_files.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_files.m2 index 311a6b075a6..8207d416a48 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, File }, Subnodes => { TO printString, TO stdio, 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_groebner_bases.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_groebner_bases.m2 index 503223b8466..21f9b2dc2af 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 @@ -14,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 { @@ -117,6 +127,12 @@ 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 @@ -141,6 +157,13 @@ document { -- needsPackage "Elimination" 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 @@ -223,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 @@ -266,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);", @@ -464,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_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_modules.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 index 9857150a007..c9ff9063f21 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_modules.m2 @@ -5,7 +5,15 @@ 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 { + {"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, ".", @@ -13,22 +21,21 @@ document { 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", @@ -274,114 +282,140 @@ 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", + "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 +505,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 +779,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 +913,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 +945,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..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), @@ -90,6 +89,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 +289,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 +345,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 +378,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 +394,19 @@ 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" + }, + Subnodes => { + TO (kernel, RingMap), + TO coimage + } } undocumented { (symbol SPACE, RingMap, Number) 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", diff --git a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 index cfcd006ce94..85d1afa3184 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 +++ b/M2/Macaulay2/packages/Macaulay2Doc/ov_top.m2 @@ -11,111 +11,76 @@ 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, 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"@. + 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 @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 - :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 + :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" - :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")@ - :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" - :Mathematical Computations - > "elementary arithmetic" - > "commutative algebra" - > "homological algebra" - > "algebraic geometry" - > "combinatorics" - > "analytic functions" - Tree - :Appendix + :Doing Mathematics + :Tutorials and Examples + :@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" + > "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" - -- Mike wanted this: TO "frequently encountered problems" > "replacements for commands and scripts from Macaulay" - 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 - - Kinsun 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 - 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, - 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." } - }@ + :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. /// end-- 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)", } } diff --git a/M2/Macaulay2/packages/Macaulay2Doc/tu_modules.m2 b/M2/Macaulay2/packages/Macaulay2Doc/tu_modules.m2 deleted file mode 100644 index 5715ea716a3..00000000000 --- a/M2/Macaulay2/packages/Macaulay2Doc/tu_modules.m2 +++ /dev/null @@ -1,263 +0,0 @@ --- 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}) 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/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/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/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/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/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/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"}, 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/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/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/PrimaryDecomposition.m2 b/M2/Macaulay2/packages/PrimaryDecomposition.m2 index a5f3d330937..cb14a608d05 100644 --- a/M2/Macaulay2/packages/PrimaryDecomposition.m2 +++ b/M2/Macaulay2/packages/PrimaryDecomposition.m2 @@ -519,22 +519,25 @@ 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; + 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^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 +548,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 -- @@ -569,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 - 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^p(M,R); J := annihilator E; cokernel generators saturate(image presentation M, J)) ) diff --git a/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 b/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 index c63c64da557..d1af42f199e 100644 --- a/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 +++ b/M2/Macaulay2/packages/PrimaryDecomposition/doc.m2 @@ -117,6 +117,31 @@ 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.Strategy, 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, @@ -130,9 +155,14 @@ Node and can be obtained by using @TO (associatedPrimes, Ideal)@. Example associatedPrimes I / print; - Caveat - -- FIXME - The ground ring must be a prime field. + 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) @@ -213,15 +243,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. @@ -430,13 +459,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)"@ 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/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/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/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/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 /// 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 - 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, 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" diff --git a/M2/Macaulay2/packages/Saturation.m2 b/M2/Macaulay2/packages/Saturation.m2 index 7cd9c8c1a16..cc129236b0f 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 => 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? @@ -901,3 +901,6 @@ elapsedTime saturate(J, I, Strategy => Eliminate); degree I elapsedTime(J : I_0); + + + 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/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); 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") - 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 /// 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/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 { 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/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 /// 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, 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 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 /// 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 + /// } diff --git a/M2/Macaulay2/packages/Tutorials.m2 b/M2/Macaulay2/packages/Tutorials.m2 new file mode 100644 index 00000000000..aeed0837178 --- /dev/null +++ b/M2/Macaulay2/packages/Tutorials.m2 @@ -0,0 +1,75 @@ +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" + > "Beginner tutorial: Shidoku" + > "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) + +load "./Tutorials/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_beginnerSudoku.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/Tutorials/tu_NAG.m2 b/M2/Macaulay2/packages/Tutorials/tu_NAG.m2 new file mode 100644 index 00000000000..6a22f22dfd3 --- /dev/null +++ b/M2/Macaulay2/packages/Tutorials/tu_NAG.m2 @@ -0,0 +1,286 @@ +doc /// +Node + Key + "Tutorial: Numerical algebraic geometry" + Headline + Numerical algebraic geometry + Description + Text + 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: + + 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 find (approximate) solutions of systems of polynomial equations. + + Traditionally, polynomial systems are studied using symbolic methods + 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. + + 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)} -- solutions to g + track(g,f,solsS) + + Text + 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 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"@ + + 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 + p = sample first W -- sampling a point from the first component + evaluate(gens I, p) + + 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" + 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}}; -- 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. + + 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 + 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" + "NumericalSchubertCalculus" + +/// 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" + }@ +/// 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 96% rename from M2/Macaulay2/packages/Macaulay2Doc/tu_elementary1.m2 rename to M2/Macaulay2/packages/Tutorials/tu_elementary1.m2 index 4be38fa733a..dfba7037242 100644 --- a/M2/Macaulay2/packages/Macaulay2Doc/tu_elementary1.m2 +++ b/M2/Macaulay2/packages/Tutorials/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. diff --git a/M2/Macaulay2/packages/Tutorials/tu_modules.m2 b/M2/Macaulay2/packages/Tutorials/tu_modules.m2 new file mode 100644 index 00000000000..fc4bbeabad5 --- /dev/null +++ b/M2/Macaulay2/packages/Tutorials/tu_modules.m2 @@ -0,0 +1,383 @@ +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 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/"}, 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 /// 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 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 2db45c52c27..86c433f5a90 100644 --- a/README.md +++ b/README.md @@ -19,7 +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 brief instructions, see [here](https://github.com/Macaulay2/M2/wiki/Git-for-Macaulay2-Contributors). +For the current contribution workflow, use the Macaulay2 wiki: + +* [Git for Macaulay2 Contributors](https://github.com/Macaulay2/M2/wiki/Git-for-Macaulay2-Contributors) +* [Pull requests](https://github.com/Macaulay2/M2/wiki/Pull-requests) + +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. + +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